bugsnag Traces API

openapi: 3.2.0
info:
  title: Bugsnag Traces API
  version: '1.0'
  description: 'Operations tagged Traces across 2 of this provider''s published API definitions: bugsnag-trace-openapi.yml, bugsnag-traces-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://otlp.bugsnag.com:4318
  description: Bugsnag OTLP HTTP Endpoint. The project API key should be prepended as a subdomain (e.g., {apiKey}.otlp.bugsnag.com:4318).
- description: For organizations with projects on app.bugsnag.com
  url: https://otlp.bugsnag.com
- description: For organizations with projects on app.bugsnag.smartbear.com
  url: https://otlp.bugsnag.smartbear.com
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/smartbear-public/bugsnag-trace-api/1
tags:
- name: Traces
  description: Send OpenTelemetry trace data to Bugsnag for performance monitoring. Spans represent individual operations and are assembled into traces that visualize request flow and latency.
paths:
  /v1/traces:
    post:
      operationId: sendTraces
      summary: Send trace data
      description: Sends OpenTelemetry span data to Bugsnag using the OTLP HTTP protocol. Accepts payloads in JSON format (application/json) or protobuf format (application/x-protobuf). Spans represent individual operations such as HTTP requests, database queries, or function calls. Bugsnag assembles spans into traces to visualize request flow and identify performance bottlenecks. The maximum payload size is 1MB, and a batch size of approximately 200 spans is recommended.
      tags:
      - Traces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportTraceServiceRequest'
          application/x-protobuf:
            schema:
              type: string
              format: binary
              description: Protobuf-encoded OTLP ExportTraceServiceRequest.
      responses:
        '200':
          description: The trace data was accepted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportTraceServiceResponse'
        '400':
          description: The payload was malformed or invalid.
        '413':
          description: The payload exceeds the 1MB maximum size limit.
        '429':
          description: Rate limit or quota exceeded. Unmanaged span quota may be exhausted for the day.
    servers:
    - url: https://otlp.bugsnag.com:4318
      description: Bugsnag OTLP HTTP Endpoint. The project API key should be prepended as a subdomain (e.g., {apiKey}.otlp.bugsnag.com:4318).
  /traces/v1:
    servers:
    - description: For organizations with projects on app.bugsnag.com
      url: https://otlp.bugsnag.com
    - description: For organizations with projects on app.bugsnag.smartbear.com
      url: https://otlp.bugsnag.smartbear.com
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/smartbear-public/bugsnag-trace-api/1
    post:
      tags:
      - Traces
      summary: Send trace reports
      responses:
        '200':
          description: The payload was accepted and will be processed asynchronously. This doesn’t imply that your payload was valid, just that it was enqueued to be processed.
          headers:
            Bugsnag-Sampling-Probability:
              schema:
                type: string
              description: The next sampling probability that should be used with your trace reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseBody'
            application/x-protobuf:
              schema:
                $ref: '#/components/schemas/SuccessResponseBody'
        '400':
          description: The payload body was missing, or the `Bugsnag-Span-Sampling` header was empty or not present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
            application/x-protobuf:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '401':
          description: Invalid integrity header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
            application/x-protobuf:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '408':
          description: The payload took too long (>30s) to read from the network.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
            application/x-protobuf:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '413':
          description: The payload was too large (greater than 1MB).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
            application/x-protobuf:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
      parameters:
      - name: Bugsnag-Api-Key
        in: header
        description: The API Key associated with the project.  Informs Bugsnag which project has generated this trace report.
        schema:
          type: string
        required: true
      - name: Bugsnag-Span-Sampling
        in: header
        description: "A concatenation of the probability that the spans in this trace report will be sampled (kept), and the number of spans in this trace report. The format is `a:b`, where\n\n  - `a` is the probability between 0 and 1, where 1 means that all in this trace report will be sampled.\n  - `b` is the number of spans in this trace report\n"
        example: '1:1'
        required: true
        schema:
          type: string
      - name: Bugsnag-Integrity
        in: header
        description: The SHA1 hash of the payload body, to ensure the payload has not changed enroute.
        schema:
          type: string
      - name: Bugsnag-Sent-At
        in: header
        description: 2024-01-01T15:00:00.000Z - The time (in ISO 8601 format) that the trace payload is being sent.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payload'
            example:
              resourceSpans:
              - resource:
                  attributes:
                  - key: deployment.environment
                    value:
                      stringValue: development
                  - key: device.id
                    value:
                      stringValue: cl7fvqte300003b68a6m9ria1e
                  - key: device.manufacturer
                    value:
                      stringValue: xiaomi
                  - key: device.model.identifier
                    value:
                      stringValue: m2101k9g
                  - key: host.arch
                    value:
                      stringValue: arm64
                  - key: os.name
                    value:
                      stringValue: Android
                  - key: os.version
                    value:
                      stringValue: '13'
                  - key: bugsnag.app.platform
                    value:
                      stringValue: android
                  - key: browser.user_agent
                    value:
                      stringValue: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36
                  - key: browser.platform
                    value:
                      stringValue: android
                  - key: browser.mobile
                    value:
                      boolValue: true
                  - key: bugsnag.app.version_code
                    value:
                      stringValue: '1234'
                  - key: telemetry.sdk.name
                    value:
                      stringValue: bugsnag.performance.browser
                  - key: telemetry.sdk.version
                    value:
                      stringValue: 0.3.0
                  - key: service.version
                    value:
                      stringValue: 1.0.0
                scopeSpans:
                - spans:
                  - attributes:
                    - key: net.host.connection.type
                      value:
                        stringValue: cell
                    - key: net.host.connection.subtype
                      value:
                        stringValue: LTE
                    - key: http.url
                      value:
                        stringValue: https:example.com
                    - key: http.method
                      value:
                        stringValue: GET
                    - key: http.status_code
                      value:
                        stringValue: '200'
                    - key: http.request_content_length
                      value:
                        stringValue: '1024'
                    - key: http.request_content_length_uncompressed
                      value:
                        stringValue: '2048'
                    - key: http.response_content_length
                      value:
                        stringValue: '128'
                    - key: http.response_content_length_uncompressed
                      value:
                        stringValue: '256'
                    - key: http.flavor
                      value:
                        stringValue: HTTP/3
                    - key: bugsnag.browser.page.url
                      value:
                        stringValue: https://example.com
                    - key: bugsnag.browser.page.referrer
                      value:
                        stringValue: https://example.com/home
                    - key: bugsnag.browser.page.title
                      value:
                        stringValue: Example Page
                    - key: bugsnag.browser.page.route
                      value:
                        stringValue: /users/:userId
                    - key: bugsnag.browser.page.previous_route
                      value:
                        stringValue: /users
                    - key: bugsnag.span.category
                      value:
                        stringValue: full_page_load
                    - key: bugsnag.app_start.type
                      value:
                        stringValue: HOT
                    - key: bugsnag.phase
                      value:
                        stringValue: viewDidLoad
                    - key: bugsnag.view.type
                      value:
                        stringValue: UIKit
                    - key: bugsnag.view.name
                      value:
                        stringValue: Main View
                    - key: bugsnag.navigation.route
                      value:
                        stringValue: Users
                    - key: bugsnag.navigation.previous_route
                      value:
                        stringValue: Items
                    - key: bugsnag.metrics.cls
                      value:
                        doubleValue: 1.2398342829557185e-05
                    - key: bugsnag.sampling.p
                      value:
                        doubleValue: 1.0
                    endTimeUnixNano: '1690463973946200000'
                    events:
                    - name: fcp
                      timeUnixNano: '1690463973147900000'
                    - name: ttfb
                      timeUnixNano: '1690463972897500000'
                    - name: lcp
                      timeUnixNano: '1690463973774100000'
                    kind: SPAN_KIND_INTERNAL
                    name: '[FullPageLoad]/users/:userId'
                    spanId: 4fddc75f583a72ee
                    startTimeUnixNano: '1690463972520200000'
                    traceId: aa8b83c28b86bd6357a62b64462341a1
          application/x-protobuf:
            schema:
              $ref: '#/components/schemas/Payload'
      operationId: postTracesV1
      x-operation-id-source: derived
components:
  schemas:
    ExportTraceServiceRequest:
      type: object
      description: The OTLP ExportTraceServiceRequest containing resource spans. This follows the OpenTelemetry protocol specification.
      properties:
        resourceSpans:
          type: array
          description: A collection of spans from a single resource (service).
          items:
            $ref: '#/components/schemas/ResourceSpans'
    Span:
      type: object
      description: Represents a single operation within a trace. Spans have a name, start and end time, and attributes describing the operation.
      properties:
        traceId:
          type: string
          description: The trace identifier, a 32-character hex string shared by all spans in the same trace.
        spanId:
          type: string
          description: The span identifier, a 16-character hex string unique to this span.
        parentSpanId:
          type: string
          description: The span identifier of the parent span. Empty for root spans.
        name:
          type: string
          description: A descriptive name for the operation (e.g., HTTP GET /api/users).
        kind:
          type: integer
          description: The span kind indicating the relationship between the span and its parent. 0=Unspecified, 1=Internal, 2=Server, 3=Client, 4=Producer, 5=Consumer.
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
        startTimeUnixNano:
          type: string
          description: The start time of the span in nanoseconds since Unix epoch.
        endTimeUnixNano:
          type: string
          description: The end time of the span in nanoseconds since Unix epoch.
        attributes:
          type: array
          description: Key-value attributes describing the span's operation.
          items:
            $ref: '#/components/schemas/KeyValue'
        status:
          type: object
          description: The status of the span operation.
          properties:
            code:
              type: integer
              description: The status code. 0=Unset, 1=Ok, 2=Error.
              enum:
              - 0
              - 1
              - 2
            message:
              type: string
              description: An optional status message.
        events:
          type: array
          description: Time-stamped events that occurred during the span.
          items:
            type: object
            properties:
              timeUnixNano:
                type: string
                description: The event time in nanoseconds since Unix epoch.
              name:
                type: string
                description: The event name.
              attributes:
                type: array
                description: Key-value attributes for the event.
                items:
                  $ref: '#/components/schemas/KeyValue'
    ExportTraceServiceResponse:
      type: object
      description: The response to an OTLP trace export request.
      properties:
        partialSuccess:
          type: object
          description: Information about partially successful exports.
          properties:
            rejectedSpans:
              type: integer
              description: The number of spans that were rejected.
            errorMessage:
              type: string
              description: An error message if some spans were rejected.
    KeyValue:
      type: object
      description: A key-value pair used for attributes in the OpenTelemetry data model.
      properties:
        key:
          type: string
          description: The attribute key.
        value:
          type: object
          description: The attribute value, which can be a string, integer, double, boolean, or array.
          properties:
            stringValue:
              type: string
              description: A string value.
            intValue:
              type: string
              description: An integer value, encoded as a string.
            doubleValue:
              type: number
              description: A double-precision floating point value.
            boolValue:
              type: boolean
              description: A boolean value.
    ResourceSpans:
      type: object
      description: A collection of spans produced by a single instrumented resource.
      properties:
        resource:
          type: object
          description: The resource producing the spans, typically identifying the service name and version.
          properties:
            attributes:
              type: array
              description: Key-value attributes describing the resource.
              items:
                $ref: '#/components/schemas/KeyValue'
        scopeSpans:
          type: array
          description: A collection of spans grouped by instrumentation scope.
          items:
            $ref: '#/components/schemas/ScopeSpans'
    ScopeSpans:
      type: object
      description: A collection of spans from a single instrumentation scope (library or component).
      properties:
        scope:
          type: object
          description: The instrumentation scope that produced the spans.
          properties:
            name:
              type: string
              description: The name of the instrumentation scope.
            version:
              type: string
              description: The version of the instrumentation scope.
        spans:
          type: array
          description: The individual spans within this scope.
          items:
            $ref: '#/components/schemas/Span'
    Span_2:
      type: object
      required:
      - attributes
      - endTimeUnixNano
      - events
      - kind
      - name
      - spanId
      - startTimeUnixNano
      - traceId
      - parentSpanId
      properties:
        attributes:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: object
                description: One of these options must be present
                properties:
                  stringValue:
                    type: string
                  doubleValue:
                    type: number
          description: "An array of attributes for these spans, as key-value pairs\n\n```\n{\n    \"key\": \"net.host.connection.type\",\n    \"value\": {\n        \"stringValue\": \"5G\"\n    }\n},\n{\n    \"key\": \"net.host.connection.subtype\",\n    \"value\": {\n        \"stringValue\": \"5G\"\n    }\n},\n{\n    \"key\": \"http.url\",\n    \"value\": {\n        \"stringValue\": \"https:example.com\"\n    }\n},\n{\n    \"key\": \"http.method\",\n    \"value\": {\n        \"stringValue\": \"GET\"\n    }\n},\n{\n    \"key\": \"http.status_code\",\n    \"value\": {\n        \"stringValue\": \"200\"\n    }\n},\n{\n    \"key\": \"http.request_content_length\",\n    \"value\": {\n        \"stringValue\": \"1024\"\n    }\n},\n{\n    \"key\": \"http.request_content_length_uncompressed\",\n    \"value\": {\n        \"stringValue\": \"2048\"\n    }\n},\n{\n    \"key\": \"http.response_content_length\",\n    \"value\": {\n        \"stringValue\": \"128\"\n    }\n},\n{\n    \"key\": \"http.response_content_length_uncompressed\",\n    \"value\": {\n        \"stringValue\": \"256\"\n    }\n},\n{\n    \"key\": \"http.flavor\",\n    \"value\": {\n        \"stringValue\": \"HTTP/3\"\n    }\n},\n{\n    \"key\": \"bugsnag.browser.page.url\",\n    \"value\": {\n        \"stringValue\": \"https://example.com\"\n    }\n},\n{\n    \"key\": \"bugsnag.browser.page.referrer\",\n    \"value\": {\n        \"stringValue\": \"https://example.com/home\"\n    }\n},\n{\n    \"key\": \"bugsnag.browser.page.title\",\n    \"value\": {\n        \"stringValue\": \"Example Page\"\n    }\n},\n{\n    \"key\": \"bugsnag.browser.page.route\",\n    \"value\": {\n        \"stringValue\": \"/users/:userId\"\n    }\n},\n{\n    \"key\": \"bugsnag.browser.page.previous_route\",\n    \"value\": {\n        \"stringValue\": \"/users\"\n    }\n},\n{\n    \"key\": \"bugsnag.span.category\",\n    \"value\": {\n        \"stringValue\": \"full_page_load\"\n    }\n},\n{\n    \"key\": \"bugsnag.app_start.type\",\n    \"value\": {\n        \"stringValue\": \"HOT\"\n    }\n},\n{\n    \"key\": \"bugsnag.phase\",\n    \"value\": {\n        \"stringValue\": \"viewDidLoad\"\n    }\n},\n{\n    \"key\": \"bugsnag.view.type\",\n    \"value\": {\n        \"stringValue\": \"UIKit\"\n    }\n},\n{\n    \"key\": \"bugsnag.view.name\",\n    \"value\": {\n        \"stringValue\": \"Main View\"\n    }\n},\n{\n    \"key\": \"bugsnag.navigation.route\",\n    \"value\": {\n        \"stringValue\": \"Users\"\n    }\n},\n{\n    \"key\": \"bugsnag.navigation.previous_route\",\n    \"value\": {\n        \"stringValue\": \"Items\"\n    }\n},\n{\n    \"key\": \"bugsnag.metrics.cls\",\n    \"value\": {\n        \"doubleValue\": 1.2398342829557184e-05\n    }\n},\n{\n    \"key\": \"bugsnag.sampling.p\",\n    \"value\": {\n        \"doubleValue\": 1.0\n    }\n}\n```"
        startTimeUnixNano:
          type: string
          description: The Unix epoch of when this span started
        endTimeUnixNano:
          type: string
          description: The Unix epoch of when this span ended
        events:
          type: array
          description: "An array of events that occurred in this span\n```\n  {\n      \"name\": \"fcp\",\n      \"timeUnixNano\": \"1690463973147900000\"\n  },\n  {\n      \"name\": \"ttfb\",\n      \"timeUnixNano\": \"1690463972897500000\"\n  },\n  {\n      \"name\": \"lcp\",\n      \"timeUnixNano\": \"1690463973774100000\"\n  }\n```"
          items:
            type: object
            required:
            - name
            - timeUnixNano
            properties:
              name:
                type: string
              timeUnixNano:
                description: The Unix epoch of when this event occurred
                type: string
        kind:
          type: integer
          description: The kind of span this is. See [here](https://opentelemetry.io/docs/specs/otel/trace/api/#spankind) for more information
        name:
          type: string
          description: The name of the span
        spanId:
          type: string
          description: The ID of the span
        traceId:
          type: string
          description: The ID of the trace
        parentSpanId:
          type: string
          description: The ID of the parent for this span. If this is the root span, parentSpanId should be `null`.
    SuccessResponseBody:
      type: object
      description: ExportTraceServiceResponse See [here](https://opentelemetry.io/docs/specs/otlp/) for more information
      properties:
        partial_success:
          type: object
          description: ExportTracePartialSuccess optionally used to convey warnings/suggestions to senders even when the request was fully accepted.
          properties:
            rejected_spans:
              type: integer
              description: The number of spans that were rejected, field holding a `0` value indicates that the request was fully accepted.
            error_message:
              type: string
              description: A developer-facing human-readable message in English. It should be used either to explain why the server rejected parts of the data during a partial success or to convey warnings/suggestions during a full success
    Payload:
      type: object
      required:
      - resourceSpans
      properties:
        resourceSpans:
          type: array
          items:
            $ref: '#/components/schemas/ResourceSpan'
          description: An array of trace reports that will be sent to BugSnag. Should contain at least 1 report.
    ResourceSpan:
      type: object
      required:
      - resource
      - scopeSpans
      properties:
        resource:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
          description: Metadata about where the span was generated from
        scopeSpans:
          type: array
          items:
            $ref: '#/components/schemas/Span_2'
          description: Describes a unit of work or operation. A trace can be made up of multiple spans
    Resource:
      type: object
      required:
      - attributes
      properties:
        attributes:
          description: "An array of attributes for this resource, as key-value pairs\n  ```\n  {\n    \"key\": \"deployment.environment\",\n    \"value\": {\n        \"stringValue\": \"development\"\n    }\n  },\n  {\n      \"key\": \"device.id\",\n      \"value\": {\n          \"stringValue\": \"cl7fvqte300003b68a6m9ria1e\"\n      }\n  },\n  {\n      \"key\": \"device.manufacturer\",\n      \"value\": {\n          \"stringValue\": \"xiaomi\"\n      }\n  },\n  {\n      \"key\": \"device.model.identifier\",\n      \"value\": {\n          \"stringValue\": \"m2101k9g\"\n      }\n  },\n  {\n      \"key\": \"host.arch\",\n      \"value\": {\n          \"stringValue\": \"arm64\"\n      }\n  },\n  {\n      \"key\": \"os.name\",\n      \"value\": {\n          \"stringValue\": \"Android\"\n      }\n  },\n  {\n      \"key\": \"os.version\",\n      \"value\": {\n          \"stringValue\": \"13\"\n      }\n  },\n  {\n      \"key\": \"bugsnag.app.platform\",\n      \"value\": {\n          \"stringValue\": \"android\"\n      }\n  },\n  {\n      \"key\": \"browser.user_agent\",\n      \"value\": {\n          \"stringValue\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36\"\n      }\n  },\n  {\n      \"key\": \"browser.platform\",\n      \"value\": {\n          \"stringValue\": \"android\"\n      }\n  },\n  {\n      \"key\": \"browser.mobile\",\n      \"value\": {\n          \"boolValue\": true\n      }\n  },\n  {\n      \"key\": \"bugsnag.app.version_code\",\n      \"value\": {\n          \"stringValue\": \"1234\"\n      }\n  },\n  {\n      \"key\": \"telemetry.sdk.name\",\n      \"value\": {\n          \"stringValue\": \"bugsnag.performance.browser\"\n      }\n  },\n  {\n      \"key\": \"telemetry.sdk.version\",\n      \"value\": {\n          \"stringValue\": \"0.3.0\"\n      }\n  },\n  {\n      \"key\": \"service.version\",\n      \"value\": {\n          \"stringValue\": \"1.0.0\"\n      }\n  }\n  ```\n"
          type: array
          items:
            type: object
            required:
            - key
            - value
            properties:
              key:
                type: string
              value:
                type: object
                description: One of these options must be present
                properties:
                  stringValue:
                    type: string
                  boolValue:
                    type: boolean
    ErrorResponseBody:
      type: object
      description: Status.WithDetails see[here](https://pkg.go.dev/google.golang.org/grpc/status#Status.WithDetails) for more information
      required:
      - code
      - message
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]
        message:
          type: string
          description: A developer-facing error message, which should be in English.
externalDocs:
  description: Bugsnag Performance Trace Documentation
  url: https://docs.bugsnag.com/performance/sending-traces/
x-refined-from:
- bugsnag-trace-openapi.yml
- bugsnag-traces-api-openapi.yml