# Anatomy of a SPAN

# 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`).