Jaeger

Jaeger Collector API

The Jaeger Collector ingests spans over multiple protocols — native Jaeger api_v2 (gRPC 14250, HTTP 14268), OTLP (gRPC 4317, HTTP 4318), and Zipkin (HTTP 9411) — and writes them to the configured storage backend (Cassandra, OpenSearch, Elasticsearch, ClickHouse, Kafka, or Badger). In Jaeger v2 the Collector is a customized OpenTelemetry Collector distribution.

Jaeger Collector API is one of 3 APIs that Jaeger publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Observability, Distributed Tracing, and Ingest. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

GitHub OpenAPI

Documentation

📖
Documentation
https://www.jaegertracing.io/docs/latest/apis/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/jaeger-io/refs/heads/main/openapi/jaeger-collector-api-openapi.yml

Other Resources

🔗
ProtoBuf
https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v2/collector.proto
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/jaeger-io/refs/heads/main/capabilities/collector-ingest.yaml

OpenAPI Specification

jaeger-collector-api-openapi.yml Raw ↑ 
# Hand-derived from https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v2/collector.proto
# Jaeger CollectorService gRPC + HTTP gateway. Spans are POSTed to the
# Collector for storage and indexing.

openapi: 3.0.3
info:
  title: Jaeger Collector API (api_v2)
  version: '2.0'
  description: |-
    Jaeger Collector ingest API. The Collector accepts span batches over gRPC
    on port 14250 (`jaeger.api_v2.CollectorService`) and over the HTTP gateway
    at `/api/v2/spans`. Jaeger v2 (since November 2024) also accepts OTLP
    natively on ports 4317 (gRPC) and 4318 (HTTP) and Zipkin on 9411; this
    spec documents the native legacy api_v2 surface.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:14268
    description: Jaeger Collector legacy HTTP endpoint
paths:
  /api/v2/spans:
    post:
      summary: Post Spans
      description: |-
        Submit a batch of spans to the Jaeger Collector for storage. The
        gRPC equivalent is `CollectorService/PostSpans`.
      operationId: postSpans
      tags:
        - CollectorService
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSpansRequest'
          application/x-protobuf:
            schema:
              $ref: '#/components/schemas/PostSpansRequest'
      responses:
        '200':
          description: Spans accepted by the collector.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSpansResponse'
components:
  schemas:
    PostSpansRequest:
      type: object
      required:
        - batch
      properties:
        batch:
          $ref: '#/components/schemas/Batch'
    PostSpansResponse:
      type: object
      description: Empty response — successful ingest is signaled by 200 OK.
    Batch:
      type: object
      description: A batch of spans from a single process. Mirrors `jaeger.api_v2.model.Batch`.
      properties:
        process:
          $ref: '#/components/schemas/Process'
        spans:
          type: array
          items:
            $ref: '#/components/schemas/Span'
    Process:
      type: object
      properties:
        serviceName:
          type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/KeyValue'
    Span:
      type: object
      properties:
        traceId:
          type: string
          description: 16-byte trace identifier, hex-encoded.
        spanId:
          type: string
          description: 8-byte span identifier, hex-encoded.
        operationName:
          type: string
        references:
          type: array
          items:
            $ref: '#/components/schemas/SpanRef'
        flags:
          type: integer
          format: int32
        startTime:
          type: string
          format: date-time
        duration:
          type: string
          description: Duration in protobuf Duration format.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/KeyValue'
        logs:
          type: array
          items:
            $ref: '#/components/schemas/Log'
    SpanRef:
      type: object
      properties:
        traceId:
          type: string
        spanId:
          type: string
        refType:
          type: string
          enum: [CHILD_OF, FOLLOWS_FROM]
    Log:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        fields:
          type: array
          items:
            $ref: '#/components/schemas/KeyValue'
    KeyValue:
      type: object
      properties:
        key:
          type: string
        vType:
          type: string
          enum: [STRING, BOOL, INT64, FLOAT64, BINARY]
        vStr:
          type: string
        vBool:
          type: boolean
        vInt64:
          type: integer
          format: int64
        vFloat64:
          type: number
          format: double
        vBinary:
          type: string
          format: byte