Elastic Observability event intake API

openapi: 3.2.0
info:
  title: Observability Intake event intake API
  description: OpenAPI schema for Observability Intake APIs
  version: '0.1'
  license:
    name: Elastic License 2.0
    url: https://www.elastic.co/licensing/elastic-license
  contact:
    name: APM Team
servers:
- url: /
security:
- apiKeyAuth: []
- secretToken: []
tags:
- name: event intake
  description: The events intake API is the internal protocol that APM agents use to talk to the APM Server.
  x-displayName: APM event intake
paths:
  /intake/v2/events:
    post:
      summary: Send APM agent events
      description: 'NOTE: Most users do not need to interact directly with the events intake API. Agents communicate with the APM Server by sending events--captured pieces of information--in an HTTP request. Events can be transactions, spans, errors, or metrics. Each event is sent as its own line in the HTTP request body, which is known as newline delimited JSON (NDJSON). With NDJSON, agents can open an HTTP POST request and use chunked encoding to stream events to the APM Server as soon as they are recorded in the agent. This makes it simple for agents to serialize each event to a stream of newline delimited JSON. The APM Server also treats the HTTP body as a compressed stream and thus reads and handles each event independently. See the [APM data model](https://www.elastic.co/guide/en/observability/current/apm-data-model.html) to learn more about the different types of events.

        '
      operationId: postEventIntake
      tags:
      - event intake
      requestBody:
        content:
          application/ndjson:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ErrorEvent'
              - $ref: '#/components/schemas/MetadataEvent'
              - $ref: '#/components/schemas/MetricSetEvent'
              - $ref: '#/components/schemas/SpanEvent'
              - $ref: '#/components/schemas/TransactionEvent'
            examples:
              postMetadataEventIntakeExample:
                $ref: '#/components/examples/metadataEventIntakeRequestExample'
              postMetricSetEventIntakeExample:
                $ref: '#/components/examples/metricSetEventIntakeRequestExample'
      responses:
        '202':
          description: Successful response; all events succeeded.
  /intake/v2/rum/events:
    post:
      summary: Send RUM events
      description: 'NOTE: Most users do not need to interact directly with the events intake API.

        '
      operationId: postRumEventIntakeV2
      tags:
      - event intake
      requestBody:
        content:
          application/ndjson:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ErrorEvent'
              - $ref: '#/components/schemas/MetadataEvent'
              - $ref: '#/components/schemas/MetricSetEvent'
              - $ref: '#/components/schemas/SpanEvent'
              - $ref: '#/components/schemas/TransactionEvent'
      responses:
        '202':
          description: Successful response; all events succeeded.
  /intake/v3/rum/events:
    post:
      summary: Send RUM events
      description: 'NOTE: Most users do not need to interact directly with the events intake API.

        '
      operationId: postRumEventIntakeV3
      tags:
      - event intake
      requestBody:
        content:
          application/ndjson:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ErrorEventv3'
              - $ref: '#/components/schemas/MetadataEventv3'
              - $ref: '#/components/schemas/SpanEventv3'
              - $ref: '#/components/schemas/TransactionEventv3'
      responses:
        '202':
          description: Successful response; all events succeeded.
components:
  examples:
    metricSetEventIntakeRequestExample:
      summary: A request body example for the metricset event type.
      value:
        metricset:
          samples:
            transaction.breakdown.count:
              value: 12
            transaction.duration.sum.us:
              value: 12
            transaction.duration.count:
              value: 2
            transaction.self_time.sum.us:
              value: 10
            transaction.self_time.count:
              value: 2
            span.self_time.count:
              value: 1
            span.self_time.sum.us:
              value: 633.288
            byte_counter:
              value: 1
            short_counter:
              value: 227
            integer_gauge:
              value: 42767
            long_gauge:
              value: 3147483648
            float_gauge:
              value: 9.16
            double_gauge:
              value: 3.141592653589793
            dotted.float.gauge:
              value: 6.12
            negative.d.o.t.t.e.d:
              value: -1022
          tags:
            code: 200
            success: true
          transaction:
            type: request
            name: GET/
          span:
            type: db
            subtype: mysql
          timestamp: 1571657444929001
    metadataEventIntakeRequestExample:
      summary: A request body example for the metadata event type.
      value:
        metadata:
          process:
            pid: 1234
            title: /usr/lib/jvm/java-10-openjdk-amd64/bin/java
            ppid: 1
            argv:
            - -v
          system:
            architecture: amd64
            detected_hostname: 8ec7ceb99074
            configured_hostname: host1
            platform: Linux
            container:
              id: 8ec7ceb990749e79b37f6dc6cd3628633618d6ce412553a552a0fa6b69419ad4
            kubernetes:
              namespace: default
              pod:
                uid: b17f231da0ad128dc6c6c0b2e82f6f303d3893e3
                name: instrumented-java-service
              node:
                name: node-name
          service:
            name: 1234_service-12a3
            version: 4.3.0
            node:
              configured_name: 8ec7ceb990749e79b37f6dc6cd3628633618d6ce412553a552a0fa6b69419ad4
            environment: production
            language:
              name: Java
              version: 10.0.2
            agent:
              version: 1.10.0
              name: java
              ephemeral_id: e71be9ac-93b0-44b9-a997-5638f6ccfc36
            framework:
              name: spring
              version: 5.0.0
            runtime:
              name: Java
              version: 10.0.2
          labels:
            group: experimental
            ab_testing: true
            segment: 5
  schemas:
    ErrorEvent:
      type: object
      description: 'Errors are events that occur in a monitored service and correspond to an error or a logged message captured by an agent.

        '
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/error'
    TransactionEventv3:
      type: object
      required:
      - transaction
      properties:
        transaction:
          $ref: '#/components/schemas/transaction-2'
    metadata:
      $id: docs/spec/v2/metadata
      type: object
      properties:
        cloud:
          description: Cloud metadata about where the monitored service is running.
          type:
          - 'null'
          - object
          properties:
            account:
              description: Account where the monitored service is running.
              type:
              - 'null'
              - object
              properties:
                id:
                  description: ID of the cloud account.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                name:
                  description: Name of the cloud account.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
            availability_zone:
              description: AvailabilityZone where the monitored service is running, e.g. us-east-1a
              type:
              - 'null'
              - string
              maxLength: 1024
            instance:
              description: Instance on which the monitored service is running.
              type:
              - 'null'
              - object
              properties:
                id:
                  description: ID of the cloud instance.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                name:
                  description: Name of the cloud instance.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
            machine:
              description: Machine on which the monitored service is running.
              type:
              - 'null'
              - object
              properties:
                type:
                  description: ID of the cloud machine.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
            project:
              description: Project in which the monitored service is running.
              type:
              - 'null'
              - object
              properties:
                id:
                  description: ID of the cloud project.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                name:
                  description: Name of the cloud project.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
            provider:
              description: Provider that is used, e.g. aws, azure, gcp, digitalocean.
              type: string
              maxLength: 1024
            region:
              description: Region where the monitored service is running, e.g. us-east-1
              type:
              - 'null'
              - string
              maxLength: 1024
            service:
              description: Service that is monitored on cloud
              type:
              - 'null'
              - object
              properties:
                name:
                  description: Name of the cloud service, intended to distinguish services running on different platforms within a provider, eg AWS EC2 vs Lambda, GCP GCE vs App Engine, Azure VM vs App Server.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
          required:
          - provider
        labels:
          description: Labels are a flat mapping of user-defined tags. Allowed value types are string, boolean and number values. Labels are indexed and searchable.
          type:
          - 'null'
          - object
          additionalProperties:
            type:
            - 'null'
            - string
            - boolean
            - number
            maxLength: 1024
        network:
          description: Network holds information about the network over which the monitored service is communicating.
          type:
          - 'null'
          - object
          properties:
            connection:
              type:
              - 'null'
              - object
              properties:
                type:
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
        process:
          description: Process metadata about the monitored service.
          type:
          - 'null'
          - object
          properties:
            argv:
              description: Argv holds the command line arguments used to start this process.
              type:
              - 'null'
              - array
              items:
                type: string
              minItems: 0
            pid:
              description: PID holds the process ID of the service.
              type: integer
            ppid:
              description: Ppid holds the parent process ID of the service.
              type:
              - 'null'
              - integer
            title:
              description: Title is the process title. It can be the same as process name.
              type:
              - 'null'
              - string
              maxLength: 1024
          required:
          - pid
        service:
          description: Service metadata about the monitored service.
          type: object
          properties:
            agent:
              description: Agent holds information about the APM agent capturing the event.
              type: object
              properties:
                activation_method:
                  description: ActivationMethod of the APM agent capturing information.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                ephemeral_id:
                  description: EphemeralID is a free format ID used for metrics correlation by agents
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                name:
                  description: Name of the APM agent capturing information.
                  type: string
                  maxLength: 1024
                  minLength: 1
                version:
                  description: Version of the APM agent capturing information.
                  type: string
                  maxLength: 1024
              required:
              - name
              - version
            environment:
              description: Environment in which the monitored service is running, e.g. `production` or `staging`.
              type:
              - 'null'
              - string
              maxLength: 1024
            framework:
              description: Framework holds information about the framework used in the monitored service.
              type:
              - 'null'
              - object
              properties:
                name:
                  description: Name of the used framework
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                version:
                  description: Version of the used framework
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
            id:
              description: ID holds a unique identifier for the running service.
              type:
              - 'null'
              - string
            language:
              description: Language holds information about the programming language of the monitored service.
              type:
              - 'null'
              - object
              properties:
                name:
                  description: Name of the used programming language
                  type: string
                  maxLength: 1024
                version:
                  description: Version of the used programming language
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
              required:
              - name
            name:
              description: Name of the monitored service.
              type: string
              maxLength: 1024
              minLength: 1
              pattern: ^[a-zA-Z0-9 _-]+$
            node:
              description: Node must be a unique meaningful name of the service node.
              type:
              - 'null'
              - object
              properties:
                configured_name:
                  description: Name of the service node
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
            runtime:
              description: Runtime holds information about the language runtime running the monitored service
              type:
              - 'null'
              - object
              properties:
                name:
                  description: Name of the language runtime
                  type: string
                  maxLength: 1024
                version:
                  description: Name of the language runtime
                  type: string
                  maxLength: 1024
              required:
              - name
              - version
            version:
              description: Version of the monitored service.
              type:
              - 'null'
              - string
              maxLength: 1024
          required:
          - agent
          - name
        system:
          description: System metadata
          type:
          - 'null'
          - object
          properties:
            architecture:
              description: Architecture of the system the monitored service is running on.
              type:
              - 'null'
              - string
              maxLength: 1024
            configured_hostname:
              description: ConfiguredHostname is the configured name of the host the monitored service is running on. It should only be sent when configured by the user. If given, it is used as the event's hostname.
              type:
              - 'null'
              - string
              maxLength: 1024
            container:
              description: Container holds the system's container ID if available.
              type:
              - 'null'
              - object
              properties:
                id:
                  description: ID of the container the monitored service is running in.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
            detected_hostname:
              description: DetectedHostname is the hostname detected by the APM agent. It usually contains what the hostname command returns on the host machine. It will be used as the event's hostname if ConfiguredHostname is not present.
              type:
              - 'null'
              - string
              maxLength: 1024
            host_id:
              description: The OpenTelemetry semantic conventions compliant "host.id" attribute, if available.
              type:
              - 'null'
              - string
              maxLength: 1024
            hostname:
              description: 'Deprecated: Use ConfiguredHostname and DetectedHostname instead. DeprecatedHostname is the host name of the system the service is running on. It does not distinguish between configured and detected hostname and therefore is deprecated and only used if no other hostname information is available.'
              type:
              - 'null'
              - string
              maxLength: 1024
            kubernetes:
              description: Kubernetes system information if the monitored service runs on Kubernetes.
              type:
              - 'null'
              - object
              properties:
                namespace:
                  description: Namespace of the Kubernetes resource the monitored service is run on.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                node:
                  description: Node related information
                  type:
                  - 'null'
                  - object
                  properties:
                    name:
                      description: Name of the Kubernetes Node
                      type:
                      - 'null'
                      - string
                      maxLength: 1024
                pod:
                  description: Pod related information
                  type:
                  - 'null'
                  - object
                  properties:
                    name:
                      description: Name of the Kubernetes Pod
                      type:
                      - 'null'
                      - string
                      maxLength: 1024
                    uid:
                      description: UID is the system-generated string uniquely identifying the Pod.
                      type:
                      - 'null'
                      - string
                      maxLength: 1024
            platform:
              description: Platform name of the system platform the monitored service is running on.
              type:
              - 'null'
              - string
              maxLength: 1024
        user:
          description: User metadata, which can be overwritten on a per event basis.
          type:
          - 'null'
          - object
          properties:
            domain:
              description: Domain of the logged in user
              type:
              - 'null'
              - string
              maxLength: 1024
            email:
              description: Email of the user.
              type:
              - 'null'
              - string
              maxLength: 1024
            id:
              description: ID identifies the logged in user, e.g. can be the primary key of the user
              type:
              - 'null'
              - string
              - integer
              maxLength: 1024
            username:
              description: Name of the user.
              type:
              - 'null'
              - string
              maxLength: 1024
      required:
      - service
    SpanEvent:
      type: object
      description: 'Spans are events captured by an agent occurring in a monitored service.

        '
      required:
      - span
      properties:
        span:
          $ref: '#/components/schemas/span'
    span:
      $id: docs/spec/v2/span
      type: object
      properties:
        action:
          description: Action holds the specific kind of event within the sub-type represented by the span (e.g. query, connect)
          type:
          - 'null'
          - string
          maxLength: 1024
        child_ids:
          description: ChildIDs holds a list of successor transactions and/or spans.
          type:
          - 'null'
          - array
          items:
            type: string
            maxLength: 1024
          minItems: 0
        composite:
          description: Composite holds details on a group of spans represented by a single one.
          type:
          - 'null'
          - object
          properties:
            compression_strategy:
              description: A string value indicating which compression strategy was used. The valid values are `exact_match` and `same_kind`.
              type: string
            count:
              description: Count is the number of compressed spans the composite span represents. The minimum count is 2, as a composite span represents at least two spans.
              type: integer
              minimum: 2
            sum:
              description: Sum is the durations of all compressed spans this composite span represents in milliseconds.
              type: number
              minimum: 0
          required:
          - compression_strategy
          - count
          - sum
        context:
          description: Context holds arbitrary contextual information for the event.
          type:
          - 'null'
          - object
          properties:
            db:
              description: Database contains contextual data for database spans
              type:
              - 'null'
              - object
              properties:
                instance:
                  description: Instance name of the database.
                  type:
                  - 'null'
                  - string
                link:
                  description: Link to the database server.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                rows_affected:
                  description: RowsAffected shows the number of rows affected by the statement.
                  type:
                  - 'null'
                  - integer
                statement:
                  description: Statement of the recorded database event, e.g. query.
                  type:
                  - 'null'
                  - string
                type:
                  description: Type of the recorded database event., e.g. sql, cassandra, hbase, redis.
                  type:
                  - 'null'
                  - string
                user:
                  description: User is the username with which the database is accessed.
                  type:
                  - 'null'
                  - string
            destination:
              description: Destination contains contextual data about the destination of spans
              type:
              - 'null'
              - object
              properties:
                address:
                  description: 'Address is the destination network address: hostname (e.g. ''localhost''), FQDN (e.g. ''elastic.co''), IPv4 (e.g. ''127.0.0.1'') IPv6 (e.g. ''::1'')'
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                port:
                  description: Port is the destination network port (e.g. 443)
                  type:
                  - 'null'
                  - integer
                service:
                  description: Service describes the destination service
                  type:
                  - 'null'
                  - object
                  properties:
                    name:
                      description: 'Name is the identifier for the destination service, e.g. ''http://elastic.co'', ''elasticsearch'', ''rabbitmq'' ( DEPRECATED: this field will be removed in a future release'
                      type:
                      - 'null'
                      - string
                      maxLength: 1024
                    resource:
                      description: 'Resource identifies the destination service resource being operated on e.g. ''http://elastic.co:80'', ''elasticsearch'', ''rabbitmq/queue_name'' DEPRECATED: this field will be removed in a future release'
                      type: string
                      maxLength: 1024
                    type:
                      description: 'Type of the destination service, e.g. db, elasticsearch. Should typically be the same as span.type. DEPRECATED: this field will be removed in a future release'
                      type:
                      - 'null'
                      - string
                      maxLength: 1024
                  required:
                  - resource
            http:
              description: HTTP contains contextual information when the span concerns an HTTP request.
              type:
              - 'null'
              - object
              properties:
                method:
                  description: Method holds information about the method of the HTTP request.
                  type:
                  - 'null'
                  - string
                  maxLength: 1024
                request:
                  description: Request describes the HTTP request information.
                  type:
                  - 'null'
                  - object
                  properties:
                    id:
                      description: ID holds the unique identifier for the http request.
                      type:
                      - 'null'
                      - string
                response:
                  description: Response describes the HTTP response information in case the event was created as a result of an HTTP request.
                  type:
                  - 'null'
                  - object
                  properties:
                    decoded_body_size:
                      description: DecodedBodySize holds the size of the decoded payload.
                      type:
                      - 'null'
                      - integer
                    encoded_body_size:
                      description: EncodedBodySize holds the size of the encoded payload.
                      type:
                      - 'null'
                      - integer
                    headers:
                      description: Headers holds the http headers sent in the http response.
                      type:
                      - 'null'
                      - object
                      additionalProperties: false
                      patternProperties:
                        '[.*]*$':
                          type:
                          - 'null'
                          - array
                          - string
                          items:
                            type: string
                    status_code:
                      description: StatusCode sent in the http response.
                      type:
                      - 'null'
                      - integer
                    transfer_size:
                      description: TransferSize holds the total size of the payload.
                      type:
                      - 'null'
                      - integer
                status_code:
                  description: 'Deprecated: Use Response.StatusCode instead. StatusCode sent in the http response.'
                  type:
                  - 'null'
                  - integer
                url:
                  description: URL is the raw url of the correlating HTTP request.
                  type:
                  - 'null'
                  - string
            message:
              description: Message holds details related to message receiving and publishing if the captured event integrates with a messaging system
              type:
              - 'null'
              - object
              properties:
                age:
                  description: Age of the message. If the monitored messaging framework provides a timestamp for the message, agents may use it. Otherwise, the sending agent can add a timestamp in milliseconds since the Unix epoch to the message's metadata to be retrieved by the receiving agent. If a timestamp is not available, agents should omit this field.
                  type:
                  - 'null'
                  - object
                  properties:
                    ms:
                      description: Age of the message in milliseconds.
                      type:
                      - 'null'
                      - integer
                body:
                  description: Body of the received message, similar to an HTTP request body
                  type:
                  - 'null'
                  - string
                headers:
                  description: Headers received with the message, similar to HTTP request headers.
                  type:
                  - 'null'
                  - object
                  additionalProperties: false
                  patternProperties:
                    '[.*]*$':
                      type:
                      - 'null'
                      - array
                      - string
                      items:
                        type: string
                queue:
                  description: Queue holds information about the message queue where the message is received.
                  type:
                  - 'null'
                  - object
                  properties:
                    name:
                      description: Name holds the name of the message queue where the message is received.
                      type:
                      - 'null'
                      - string
                      maxLength: 1024
                routing_key:
                  description: RoutingKey holds the optional routing key of the received message as set on the queuing system, such as in RabbitMQ.
                  type:
                  - 'null'
                  - string
            service:
              description: Service related information can be sent per span. Information provided here will override the more generic information retrieved from metadata, missing service fields will be retrieved from the metadata information.
              type:
              - 'null'
              - object
              properties:
                agent:
                  description: Agent holds information about the APM agent capturing the event.
                  type:
                  - 'null'
                  - object
                  properties:
                    ephemeral_id:
                      description: EphemeralID is a free format ID used for metrics correlation by agents
                     

# --- truncated at 32 KB (181 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-observability/refs/heads/main/openapi/elastic-observability-event-intake-api-openapi.yml