openapi: 3.1.0
info:
  title: Zipkin API v2
  description: >-
    Zipkin's v2 HTTP API for querying and collecting distributed traces. Provides
    endpoints for submitting spans, querying traces, looking up services and span
    names, and retrieving dependency links between services.
  version: 2.0.0
  contact:
    name: OpenZipkin
    url: https://zipkin.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:9411
    description: Default Zipkin server
tags:
  - name: Services
    description: Query registered service names
  - name: Spans
    description: Submit and query span names
  - name: Traces
    description: Search and retrieve distributed traces
  - name: Dependencies
    description: Query service dependency links
  - name: Autocomplete
    description: Autocomplete tag key and value lookups
  - name: Health
    description: Server health check
paths:
  /api/v2/services:
    get:
      operationId: getServices
      summary: Zipkin Get Service Names
      description: Returns a list of all service names associated with span endpoints.
      tags:
        - Services
      responses:
        '200':
          description: A list of service names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Bad request
  /api/v2/spans:
    get:
      operationId: getSpanNames
      summary: Zipkin Get Span Names
      description: Returns a list of span names for a given service.
      tags:
        - Spans
      parameters:
        - name: serviceName
          in: query
          required: true
          description: The service name to lookup span names for
          schema:
            type: string
      responses:
        '200':
          description: A list of span names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Bad request
    post:
      operationId: reportSpans
      summary: Zipkin Report Spans
      description: >-
        Uploads a list of spans encoded per content type. Accepted content types
        are application/json and application/x-protobuf.
      tags:
        - Spans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Span'
      responses:
        '202':
          description: Spans accepted
        '400':
          description: Bad request - spans were malformed
  /api/v2/traces:
    get:
      operationId: getTraces
      summary: Zipkin Search for Traces
      description: >-
        Searches for traces matching the given query parameters. Results are
        sorted by descending end timestamp.
      tags:
        - Traces
      parameters:
        - name: serviceName
          in: query
          description: Service name to query for
          schema:
            type: string
        - name: spanName
          in: query
          description: Span name to query for
          schema:
            type: string
        - name: annotationQuery
          in: query
          description: >-
            Annotation query string, e.g. "http.method=GET" or "error"
          schema:
            type: string
        - name: minDuration
          in: query
          description: Minimum duration in microseconds
          schema:
            type: integer
            format: int64
        - name: maxDuration
          in: query
          description: Maximum duration in microseconds
          schema:
            type: integer
            format: int64
        - name: endTs
          in: query
          description: >-
            Upper bound on the timestamp of the first span in a trace, in epoch
            milliseconds. Defaults to current time.
          schema:
            type: integer
            format: int64
        - name: lookback
          in: query
          description: >-
            How far back to look from endTs, in milliseconds. Defaults to
            endTs, limited to a system-configured max.
          schema:
            type: integer
            format: int64
        - name: limit
          in: query
          description: Maximum number of traces to return. Defaults to 10.
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: A list of traces, each trace is a list of spans
          content:
            application/json:
              schema:
                type: array
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/Span'
        '400':
          description: Bad request
  /api/v2/trace/{traceId}:
    get:
      operationId: getTrace
      summary: Zipkin Get a Trace by ID
      description: Returns a trace by its 16 or 32 character hex trace ID.
      tags:
        - Traces
      parameters:
        - name: traceId
          in: path
          required: true
          description: Trace ID, 16 or 32 character hex string
          schema:
            type: string
            pattern: '^[0-9a-f]{16,32}$'
      responses:
        '200':
          description: A trace as a list of spans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Span'
        '404':
          description: Trace not found
  /api/v2/dependencies:
    get:
      operationId: getDependencies
      summary: Zipkin Get Dependency Links
      description: >-
        Returns dependency links derived from spans. Dependencies show which
        services call which other services, along with call counts and error counts.
      tags:
        - Dependencies
      parameters:
        - name: endTs
          in: query
          required: true
          description: >-
            Upper bound timestamp for dependency links, in epoch milliseconds.
          schema:
            type: integer
            format: int64
        - name: lookback
          in: query
          description: How far back from endTs to look, in milliseconds.
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: A list of dependency links
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DependencyLink'
  /api/v2/autocompleteKeys:
    get:
      operationId: getAutocompleteKeys
      summary: Zipkin Get Autocomplete Keys
      description: Returns a list of tag keys configured for autocomplete.
      tags:
        - Autocomplete
      responses:
        '200':
          description: A list of autocomplete tag keys
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /api/v2/autocompleteValues:
    get:
      operationId: getAutocompleteValues
      summary: Zipkin Get Autocomplete Values
      description: Returns a list of values for a given autocomplete tag key.
      tags:
        - Autocomplete
      parameters:
        - name: key
          in: query
          required: true
          description: The tag key to lookup values for
          schema:
            type: string
      responses:
        '200':
          description: A list of autocomplete values
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /health:
    get:
      operationId: getHealth
      summary: Zipkin Health Check
      description: Returns OK if the server is healthy.
      tags:
        - Health
      responses:
        '200':
          description: Server is healthy
          content:
            text/plain:
              schema:
                type: string
                example: OK
components:
  schemas:
    Span:
      type: object
      required:
        - traceId
        - id
      properties:
        traceId:
          type: string
          description: Unique 128-bit or 64-bit trace identifier, hex encoded
          pattern: '^[0-9a-f]{16,32}$'
        parentId:
          type: string
          description: The parent span ID, hex encoded, absent if root span
          pattern: '^[0-9a-f]{16}$'
        id:
          type: string
          description: Unique 64-bit span identifier, hex encoded
          pattern: '^[0-9a-f]{16}$'
        kind:
          type: string
          description: The type of span
          enum:
            - CLIENT
            - SERVER
            - PRODUCER
            - CONSUMER
        name:
          type: string
          description: The logical operation this span represents
        timestamp:
          type: integer
          format: int64
          description: Epoch microseconds of the start of this span
        duration:
          type: integer
          format: int64
          description: Duration in microseconds of the critical path
        localEndpoint:
          $ref: '#/components/schemas/Endpoint'
        remoteEndpoint:
          $ref: '#/components/schemas/Endpoint'
        annotations:
          type: array
          description: Events that explain latency with a timestamp
          items:
            $ref: '#/components/schemas/Annotation'
        tags:
          type: object
          description: Key-value pairs providing additional context
          additionalProperties:
            type: string
        debug:
          type: boolean
          description: True if this span was sampled with debug flag
        shared:
          type: boolean
          description: True if this span ID is shared between client and server
    Endpoint:
      type: object
      description: The network context of a node in the service graph
      properties:
        serviceName:
          type: string
          description: Lower-case label of this node in the service graph
        ipv4:
          type: string
          description: IPv4 address
          format: ipv4
        ipv6:
          type: string
          description: IPv6 address
          format: ipv6
        port:
          type: integer
          description: Port number
          minimum: 0
          maximum: 65535
    Annotation:
      type: object
      required:
        - timestamp
        - value
      properties:
        timestamp:
          type: integer
          format: int64
          description: Epoch microseconds of this event
        value:
          type: string
          description: Event value, usually a short description
    DependencyLink:
      type: object
      required:
        - parent
        - child
        - callCount
      properties:
        parent:
          type: string
          description: Parent service name
        child:
          type: string
          description: Child service name
        callCount:
          type: integer
          description: Total traced calls from parent to child
        errorCount:
          type: integer
          description: Total traced calls that errored