Introduction

An OpenTelemetry Collector receives telemetry data, including spans, often in the OpenTelemetry Protocol (OTLP) format. While OTLP is primarily defined in Protobuf, it also has a JSON encoding.

Here's an example of a single OTLP trace span represented in JSON, as it might be sent to an OpenTelemetry Collector's OTLP/HTTP receiver:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "my-service"
            }
          },
          {
            "key": "host.name",
            "value": {
              "stringValue": "my-host"
            }
          }
        ]
      },
      "scopeSpans": [
        {
          "scope": {
            "name": "my-library",
            "version": "1.0.0"
          },
          "spans": [
            {
              "traceId": "5b8aa5a2d2c872e8321cf37308d69df2",
              "spanId": "051581bf3cb55c13",
              "parentSpanId": "a1b2c3d4e5f6a7b8",
              "name": "my-operation",
              "kind": "SPAN_KIND_SERVER",
              "startTimeUnixNano": "1678886400000000000",
              "endTimeUnixNano": "1678886400000005000",
              "attributes": [
                {
                  "key": "http.method",
                  "value": {
                    "stringValue": "GET"
                  }
                },
                {
                  "key": "http.status_code",
                  "value": {
                    "intValue": 200
                  }
                }
              ],
              "events": [
                {
                  "timeUnixNano": "1678886400000002000",
                  "name": "log_event",
                  "attributes": [
                    {
                      "key": "message",
                      "value": {
                        "stringValue": "Processing request"
                      }
                    }
                  ]
                }
              ],
              "status": {
                "code": "STATUS_CODE_OK"
              }
            }
          ]
        }
      ]
    }
  ]
}

Key elements in the OTLP/JSON span structure:

• resourceSpans: An array containing ResourceSpans objects. Each ResourceSpans object groups spans that originate from the same resource (e.g., a service, host, or application instance).
• resource: Describes the entity producing the telemetry, including its attributes (e.g., service.name, host.name).
• scopeSpans: An array containing ScopeSpans objects. Each ScopeSpans object groups spans that originate from the same instrumentation scope (e.g., a specific library or module within a service).
• scope: Describes the instrumentation library that generated the spans (e.g., name, version).
• spans: An array of individual Span objects.
• traceId: A unique identifier for the entire trace.
• spanId: A unique identifier for the specific span.
• parentSpanId: The ID of the parent span, establishing the hierarchical relationship within a trace.
• name: A human-readable name for the operation represented by the span.
• kind: The type of span (e.g., SPAN_KIND_SERVER, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL).
• startTimeUnixNano: and endTimeUnixNano: The start and end timestamps of the span in nanoseconds since the Unix epoch.
• attributes: Key-value pairs providing additional details about the span.
• events: A list of events that occurred during the span's lifetime, each with a timestamp, name, and attributes.
• status: The status of the span (e.g., STATUS_CODE_OK, STATUS_CODE_ERROR).