Ingest JSON and TXT logs

• Latest Dynatrace
• Explanation
• 15-min read
• Updated on Feb 06, 2026

The Log ingestion API ingests logs in JSON, TXT, and OTLP formats. On this page, we will describe the JSON and text formats. For OTLP documentation, refer to the OTLP formats.

The Log ingestion API is responsible for collecting the data and forwarding it to Dynatrace in batches.

For details regarding supported payloads, authentication, parameters, and body objects, refer to Log Monitoring API v2 - POST ingest logs.

For details regarding limitations, refer to Log Management and Analytics default limits.

Data transformation and automatic JSON parsing

The Log ingestion API collects and attempts to automatically transform log data. Each log record from the ingested batch is mapped to a single Dynatrace log record, which contains three special attributes: timestamp, loglevel, content, and key-value attributes. These four properties are set based on keys present in the input JSON object as follows.

Timestamp

Log level

Content

Attributes

Data models

There are two data models that identify how structured logs are processed by log ingestion endpoints: raw and flattened. The difference between the two is in how attributes with object values are transformed.

Raw data model

The raw data model preserves the original log structure and context, maintaining data integrity. This results in easy interaction and querying, because log record representation in Dynatrace remains the same as in the source.

We recommend using this approach for highly nested JSON logs, as it maintains the semantic meaning and relationships between data points.

The raw data model transforms the content of structured logs as described in the sections below.

Attributes with non-primitive types

Object attribute types are preserved as JSON strings. Further Dynatrace ingest stages (OpenPipeline, Logs app) support this format for easy log processing and analysis.

Array types are preserved as arrays but the contained types are unified to a single type.

{
  "content": "Transaction successfully processed.",
  "transaction": {
    "id": "TXN12345",
    "amount": 250.75
  },
  "auditTrail": [
    "Created",
    "Approved",
    3
  ]
}

{
  "content": "Transaction successfully processed.",
  "transaction" : "{\"id\": \"TXN12345\", \"amount\": 250.75}",
  "auditTrail": ["Created", "Approved", "3"]
}

Content handling

The selected input content field is always selected regardless of its type, and is converted to string type if necessary.

{
  "content": {
    "id": "TXN12345",
    "amount": 250.75
  },
  "auditTrail": [
    "Created",
    "Approved",
    3
  ]
}

{
  "content" : "{\"id\": \"TXN12345\", \"amount\": 250.75}",
  "auditTrail": ["Created", "Approved", "3"]
}

An example of a supported content attribute with an array value is given below.

{
  "transaction": {
    "id": "TXN12345",
    "amount": 250.75
  },
  "content": [
    "Created",
    "Approved",
    3
  ]
}

{
  "content": "[\"Created\", \"Approved\", 3]",
  "transaction" : "{\"id\": \"TXN12345\", \"amount\": 250.75}"
}

If no attribute from the supported content attributes is present in the input, the target content attribute is set to an empty string.

{
  "transaction": {
     "id": "TXN12345"
  },
  "auditTrail": [
    "Created",
    "Approved",
    3
  ]
}

{
  "content": "",
  "transaction" : "{\"id\": \"TXN12345\", \"amount\": 250.75}",
  "auditTrail": ["Created", "Approved", "3"]
}

The first attribute from the supported content attributes list is selected for the output content field.

{
  "message": {
    "id": "TXN12345",
    "amount": 250.75
  },
  "payload": "Transaction",
  "_raw": "Operation"
}

{
  "content": "{\"id\": \"TXN12345\", \"amount\": 250.75}",
  "payload" : "Transaction",
  "_raw": "Operation"
}

The _raw attribute is used as content only if no higher-priority supported content attribute is present.

{
  "_raw":  {
    "id": "TXN12345",
    "amount": 250.75
  },
  "auditTrail": [
    "Created",
    "Approved",
    3
  ]
}

{
  "content": "{\"id\": \"TXN12345\", \"amount\": 250.75}",
  "auditTrail": ["Created", "Approved", "3"]
}

Flattened data model

The flattened data model provides direct access to attribute values through simple key paths.

This approach is provided for compatibility reasons. It might also suit specific use cases, for example, when all nested JSON values need to be available at the root level.

Attributes with non-primitive types

In the flattened data model, nested objects in your log attributes are transformed into flat value pairs.

When a log attribute contains an object, each nested property becomes a separate attribute. This process works for attributes up to level five, while attributes beyond that level are skipped.

Array types are preserved as arrays but the contained types are unified to a single type.

{
  "content": "Transaction successfully processed.",
  "transaction": {
    "id": "TXN12345",
    "amount": 250.75
  },
  "auditTrail": [
    "Created",
    "Approved",
    3
  ]
}

{
  "content": "Transaction successfully processed.",
  "transaction.id": "TXN12345",
  "transaction.amount": 250.75,
  "auditTrail": ["Created", "Approved", "3"]
}

Name conflicts

When attributes are saved in a flattened fashion on the Dynatrace side, there may be name collisions if attributes on different levels share the same name. Dynatrace resolves this by prefixing duplicate attributes with overwritten[COUNTER].. The counter value indicates how many times the attribute name has been already encountered as a duplicate. For example:

{
  "host.name": "abc",
  "host": {"name": "xyz"}
}

{
  "host.name": "abc",
  "overwritten1.host.name": "xyz"
}

{
  "service.instance.id": "abc",
  "service": {"instance.id": "xyz", "instance": {"id": "123"}}
}

{
  "service.instance.id": "abc",
  "overwritten1.service.instance.id": "xyz",
  "overwritten2.service.instance.id": "123"
}

Content related behavior

The rules below define how the content field is selected and constructed.

No supported content attribute found

In case no supported content attribute is found, the whole JSON representation of the log event is set as the content field of the output log record. The original JSON is preserved as-is.

{
  "transaction": {
    "id": "TXN12345",
    "amount": 250.75
  }
}

{
  "content": "{\"transaction\":{\"id\":\"TXN12345\",\"amount\":250.75}}",
  "transaction": {
    "id": "TXN12345",
    "amount": 250.75
  }
}

Complex values in supported content attributes

Any attribute that is an object, including content, is treated as a standard attribute.

{
  "payload": "This will be used for content.",
  "message": {
    "id": "TXN12345",
    "amount": 250.75
  }
}

{
  "content": "This will be used for content.",
  "message.id": "TXN12345",
  "message.amount": 250.75
}

Log ingestion API attribute handling

The Log Ingestion API additionally accepts log attributes through:

These attributes are merged with those provided in the log record body according to the rules described below.

Query parameter attributes

Example

{
  "content": "Transaction successfully processed."
}

{
  "content": "Transaction successfully processed.",
  "env": ["prod", "blue"],
  "team": "payments"
}

Header-based attributes (X-Dynatrace-Attr)

The API supports a special header for passing additional attributes:

X-Dynatrace-Attr: region=eu-central-1&team=core

Rules:

Attributes precedence rules

When attributes appear in multiple places, the Log ingestion API applies attribute precedence while still preserving body values for auditability. The attributes are applied in the following order:

Override behavior

When attributes from query parameters or the header override body attributes:

Example

{
  "content": "Transaction successfully processed.",
  "team": "backend"
}

{
  "content": "Transaction successfully processed.",
  "team": "frontend",
  "overwritten1.team": "backend"
}

Billing behavior

Attributes provided through query parameters or headers are included in billing calculations.

For multi-value attributes, the attribute key contributes to billing only once, regardless of how many values are present.