diff --git a/docs/README.md b/docs/README.md index b1bb0e5c123..67ed86a4049 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,3 +8,11 @@ > * A list of all **breaking changes** are documented in [`changelogs/all-breaking-changes.asciidoc`](/changelogs/all-breaking-changes.asciidoc). > * **Sample data sets** that are injected into the docs are in the [`docs/data/`](/docs/data/) directory. > * **Specifications** that are injected into the docs are in the [`docs/spec/`](/docs/spec/) directory. + +To generate the bundled files in the [`docs/spec/openapi`](/docs/spec/openapi) directory, use [redocly bundle](https://redocly.com/docs/cli/commands/bundle/). For example: + +``` +npx @redocly/cli bundle apm-openapi.yaml --output bundled.yaml --ext yaml +npx @redocly/cli bundle apm-openapi.yaml --output bundled.json --ext json +``` + diff --git a/docs/spec/openapi/apm-openapi.yaml b/docs/spec/openapi/apm-openapi.yaml index 8cf97789c54..d4a9a84db3f 100644 --- a/docs/spec/openapi/apm-openapi.yaml +++ b/docs/spec/openapi/apm-openapi.yaml @@ -18,213 +18,55 @@ tags: description: APIs that query the APM Server for configuration changes. x-displayName: APM agent configuration - name: event intake - description: The events intake API is the internal protocol that APM agents use to talk to the APM Server. + description: >- + The events intake API is the internal protocol that APM agents use to talk + to the APM Server. x-displayName: APM event intake + - name: jaeger intake + description: > + Elastic APM natively supports Jaeger, an open-source, distributed tracing + system. + x-displayName: Jaeger event intake + - name: opentelemetry intake + description: > + The OpenTelemetry intake API uses the OpenTelemetry Protocol (OTLP) to + send traces, metrics, and logs to APM Server. OTLP is the default transfer + protocol for OpenTelemetry and is supported natively by APM Server. APM + Server supports two OTLP communication protocols on the same port: + OTLP/HTTP (protobuf) and OTLP/gRPC. + x-displayName: APM OpenTelemetry intake - name: server info description: APIs that query general APM Server information. x-displayName: APM server information paths: /: - get: - summary: Get general server information - description: | - This lightweight endpoint is useful as a server up/down health check. - To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access. - operationId: getServerHealth - tags: - - server info - responses: - '200': - $ref: '#/components/responses/200_server_info' - post: - summary: Get general server information - operationId: postServerHealth - tags: - - server info - responses: - '200': - $ref: '#/components/responses/200_server_info' + $ref: paths/server_info.yaml /config/v1/agents: - get: - summary: Get agent configuration changes - description: | - To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access. - operationId: getAgentConfig - tags: - - agent config - parameters: - - in: query - name: service.name - required: true - schema: - type: string - - in: query - name: service.environment - schema: - type: string - responses: - '200': - description: A successful response. - content: - application/json: - schema: - type: object - post: - summary: Get agent configuration changes - description: | - To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access. - operationId: postAgentConfig - tags: - - agent config - requestBody: - content: - application/json: - schema: - type: object - required: - - service - properties: - CAPTURE_BODY: - type: string - example: 'off' - service: - type: object - required: - - name - properties: - environment: - type: string - example: all - name: - type: string - example: test-service - additionalProperties: true - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: object - properties: - capture_body: - type: string - enum: - - 'off' - - errors - - transactions - - all - description: | - For transactions that are HTTP requests, the agent can optionally capture the request body (for example, POST variables). For transactions that are initiated by receiving a message from a message broker, the agent can capture the textual message body. - example: 'off' - transaction_max_spans: - type: integer - minimum: 0 - description: The maximum number of spans that are recorded per transaction. - example: 500 - transaction_sample_rate: - type: number - format: float - minimum: 0 - maximum: 1 - description: The agent samples transactions at this rate. - example: 0.3 - additionalProperties: true - '403': - description: APM Server is configured to fetch agent configuration from Elasticsearch but the configuration is invalid. - '503': - description: APM Server is starting up or Elasticsearch is unreachable. + $ref: paths/config_v1_agents.yaml /config/v1/rum/agents: - get: - summary: Get RUM agent configuration changes - description: | - To configure authenticated access to the APM server, the instructions at [APM API key](https://www.elastic.co/guide/en/observability/current/api-key.html) or [APM Secret Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) must be followed to configure the correct permissions for APM access. - operationId: getRumAgentConfig - tags: - - agent config - responses: - '200': - description: Successful response. + $ref: paths/config_v1_rum_agents.yaml /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 - parameters: - - in: query - name: async - description: | - Indicates whether to use asynchronous processing, which is supported by APM Server in 8.5.0 and later. NOTE: Since asynchronous processing defers some of the event processing to the background and takes place after the client has closed the request, some errors can't be communicated back to the client and are logged by the APM Server. Furthermore, asynchronous processing requests will only be scheduled if the APM Server can service the incoming request; requests that cannot be serviced will receive an internal error 503 "queue is full" error. - schema: - type: boolean - 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: - # postErrorEventIntakeExample: - # $ref: '#/components/examples/errorEventIntakeRequestExample' - postMetadataEventIntakeExample: - $ref: '#/components/examples/metadataEventIntakeRequestExample' - postMetricSetEventIntakeExample: - $ref: '#/components/examples/metricSetEventIntakeRequestExample' - # postSpanEventIntakeExample: - # $ref: '#/components/examples/spanEventIntakeRequestExample' - # postTransactionEventIntakeExample: - # $ref: '#/components/examples/transactionEventIntakeRequestExample' - responses: - '202': - description: Successful response; all events succeeded. + $ref: paths/intake_v2_events.yaml /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. + $ref: paths/intake_v2_rum_events.yaml /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. + $ref: paths/intake_v3_rum_events.yaml + /jaeger.api_v2.CollectorService/PostSpans: + $ref: paths/jaeger.api_v2.CollectorService_PostSpans.yaml + /jaeger.api_v2.SamplingManager/GetSamplingStrategy: + $ref: paths/jaeger.api_v2.SamplingManager_GetSamplingStrategy.yaml + /opentelemetry.proto.collector.metrics.v1.MetricsService/Export: + $ref: paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml + /opentelemetry.proto.collector.trace.v1.TraceService/Export: + $ref: paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml + /opentelemetry.proto.collector.logs.v1.LogsService/Export: + $ref: paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml + /v1/metrics: + $ref: paths/v1_metrics.yaml + /v1/traces: + $ref: paths/v1_traces.yaml + /v1/logs: + $ref: paths/v1_logs.yaml components: securitySchemes: apiKeyAuth: @@ -236,475 +78,3 @@ components: type: http scheme: bearer bearerFormat: Secret token - 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: '../v2/error.json' - ErrorEventv3: - type: object - required: - - error - properties: - error: - $ref: '../rumv3/error.json' - MetadataEvent: - type: object - description: > - Every new connection to the APM Server starts with a metadata stanza. - This provides general metadata concerning the other objects in the stream. - Rather than send this metadata information from the agent multiple times, the APM Server hangs on to this information and applies it to other objects in the stream as necessary. - TIP: Metadata is stored under context when viewing documents in Elasticsearch. - APM agents automatically read Kubernetes data and send it to the APM Server. - In most instances, agents are able to read this data from inside the container. - If this is not the case, or if you wish to override this data, you can set environment variables for the agents to read. - These environment variable are set via the Kubernetes Downward API. - required: - - metadata - properties: - metadata: - $ref: '../v2/metadata.json' - MetadataEventv3: - type: object - required: - - metadata - properties: - metadata: - $ref: '../rumv3/metadata.json' - MetricSetEvent: - type: object - description: > - Metric sets are events that contain application metric data captured by an APM agent. - required: - - metricset - properties: - metricset: - $ref: '../v2/metricset.json' - SpanEvent: - type: object - description: > - Spans are events captured by an agent occurring in a monitored service. - required: - - span - properties: - span: - $ref: '../v2/span.json' - SpanEventv3: - type: object - required: - - span - properties: - span: - $ref: '../rumv3/span.json' - TransactionEvent: - type: object - description: > - Transactions are events corresponding to an incoming request or similar task occurring in a monitored service. - required: - - transaction - properties: - transaction: - $ref: '../v2/transaction.json' - TransactionEventv3: - type: object - required: - - transaction - properties: - transaction: - $ref: '../rumv3/transaction.json' - responses: - 200_server_info: - description: A successful response indicates that the server is up. - content: - application/json: - schema: - description: If an API key or a secret token is passed along with the request, the response payload includes some information about the APM server. - type: object - properties: - build_date: - type: string - format: time-date - build_sha: - type: string - publish_ready: - type: boolean - version: - type: string - examples: - getServerHealthAuthResponse: - summary: Example APM Server information request with a secret token - value: - build_date: '2021-12-18T19:59:06Z' - build_sha: 24fe620eeff5a19e2133c940c7e5ce1ceddb1445 - publish_ready: true - version: 8.12.2 - examples: - # errorEventIntakeRequestExample: - # summary: A request body example for the error event type. - # value: - # error: - # id: '9876543210abcdeffedcba0123456789' - # timestamp: 1571657444929001 - # trace_id: 0123456789abcdeffedcba0123456789 - # parent_id: 9632587410abcdef - # transaction_id: '1234567890987654' - # transaction: - # sampled: true - # type: request - # culprit: opbeans.controllers.DTInterceptor.preHandle(DTInterceptor.java:73) - # log: - # message: Request method 'POST' not supported - # param_message: Request method 'POST' /events/:event not supported - # logger_name: http404 - # level: error - # stacktrace: - # - abs_path: /tmp/Socket.java - # filename: Socket.java - # classname: Request::Socket - # function: connect - # vars: - # key: value - # pre_context: - # - line1 - # - line2 - # context_line: line3 - # library_frame: true - # lineno: 3 - # module: java.net - # colno: 4 - # post_context: - # - line4 - # - line5 - # - filename: SimpleBufferingClientHttpRequest.java - # lineno: 102 - # function: executeInternal - # abs_path: /tmp/SimpleBufferingClientHttpRequest.java - # vars: - # key: value - # exception: - # message: Theusernamerootisunknown - # type: java.net.UnknownHostException - # handled: true - # module: org.springframework.http.client - # code: 42 - # attributes: - # foo: bar - # cause: - # - type: InternalDbError - # message: something wrong writing a file - # cause: - # - type: VeryInternalDbError - # message: disk spinning way too fast - # - type: ConnectionError - # message: on top of it,internet doesn't work - # stacktrace: - # - abs_path: /tmp/AbstractPlainSocketImpl.java - # filename: AbstractPlainSocketImpl.java - # function: connect - # vars: - # key: value - # pre_context: - # - line1 - # - line2 - # context_line: '3' - # library_frame: true - # lineno: 3 - # module: java.net - # colno: 4 - # post_context: - # - line4 - # - line5 - # - filename: AbstractClientHttpRequest.java - # lineno: 102 - # function: execute - # vars: - # key: value - # context: - # request: - # socket: - # remote_address: 12.53.12.1 - # encrypted: true - # http_version: '1.1' - # method: POST - # url: - # protocol: 'https:' - # full: https://www.example.com/p/a/t/h?query=string#hash - # hostname: www.example.com - # port: 8080 - # pathname: /p/a/t/h - # search: '?query=string' - # hash: '#hash' - # raw: /p/a/t/h?query=string#hash - # headers: - # Forwarded: for=192.168.0.1 - # host: opbeans-java:3000 - # content-length: '0' - # cookie: - # - c1=v1 - # - c2=v2 - # Elastic-Apm-Traceparent: 00-8c21b4b556467a0b17ae5da959b5f388-31301f1fb2998121-01 - # cookies: - # c1: v1 - # c2: v2 - # env: - # SERVER_SOFTWARE: nginx - # GATEWAY_INTERFACE: CGI/1.1 - # body: HelloWorld - # response: - # status_code: 200 - # headers: - # content-type: application/json - # headers_sent: true - # finished: true - # user: - # id: 99 - # username: foo - # email: user@foo.mail - # tags: - # organization_uuid: 9f0e9d64-c185-4d21-a6f4-4673ed561ec8 - # custom: - # my_key: 1 - # some_other_value: foobar - # and_objects: - # foo: - # - bar - # - baz - # service: - # name: service1 - # node: - # configured_name: node-xyz - # language: - # version: '1.2' - # framework: - # version: '1' - # name: Node - 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 - 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 - # spanEventIntakeRequestExample: - # summary: A request body example for the span event type. - # value: - # span: - # timestamp: 1571657444929001 - # type: external - # subtype: http - # id: 1234567890aaaade - # transaction_id: '1234567890987654' - # trace_id: abcdef0123456789abcdef9876543210 - # parent_id: abcdef0123456789 - # action: connect - # sync: true - # name: GET users-authenticated - # duration: 3.781912 - # stacktrace: - # - filename: DispatcherServlet.java - # lineno: 547 - # - function: render - # abs_path: /tmp/AbstractView.java - # filename: AbstractView.java - # lineno: 547 - # library_frame: true - # vars: - # key: value - # module: org.springframework.web.servlet.view - # colno: 4 - # context_line: line3 - # context: - # db: - # instance: customers - # statement: SELECT * FROM product_types WHERE user_id = ? - # type: sql - # user: postgres - # link: other.db.com - # http: - # url: http://localhost:8000 - # status_code: 302 - # method: GET - # response: - # status_code: 200 - # transfer_size: 300.12 - # encoded_body_size: 356 - # decoded_body_size: 401 - # headers: - # content-type: application/json - # service: - # name: opbeans-java-1 - # agent: - # version: 1.10.0-SNAPSHOT - # name: java - # ephemeral_id: e71be9ac-93b0-44b9-a997-5638f6ccfc36 - # transactionEventIntakeRequestExample: - # summary: A request body example for the transaction event type. - # value: - # transaction: - # timestamp: 1571657444929001 - # name: ResourceHttpRequestHandler - # type: http - # id: 4340a8e0df1906ecbfa9 - # trace_id: 0acd456789abcdef0123456789abcdef - # parent_id: abcdefabcdef01234567 - # span_count: - # started: 17 - # dropped: 0 - # duration: 32.592981 - # result: HTTP2xx - # sampled: true - # context: - # service: - # name: experimental-java - # agent: - # version: 1.10.0-SNAPSHOT - # ephemeral_id: e71be9ac-93b0-44b9-a997-5638f6ccfc36 - # request: - # socket: - # remote_address: 12.53.12.1:8080 - # encrypted: true - # http_version: '1.1' - # method: POST - # url: - # protocol: 'https:' - # full: https://www.example.com/p/a/t/h?query=string#hash - # hostname: www.example.com - # port: '8080' - # pathname: /p/a/t/h - # search: '?query=string' - # hash: '#hash' - # raw: /p/a/t/h?query=string#hash - # headers: - # user-agent: - # - Mozilla/5.0(Macintosh;IntelMacOSX10_10_5)AppleWebKit/537.36(KHTML,likeGecko)Chrome/51.0.2704.103Safari/537.36 - # - MozillaChromeEdge - # content-type: text/html - # cookie: c1=v1,c2=v2 - # Elastic-Apm-Traceparent: - # - 00-33a0bd4cceff0370a7c57d807032688e-69feaabc5b88d7e8-01 - # cookies: - # c1: v1 - # c2: v2 - # env: - # SERVER_SOFTWARE: nginx - # GATEWAY_INTERFACE: CGI/1.1 - # body: - # string: helloworld - # additional: - # foo: {} - # bar: 123 - # req: additionalinformation - # response: - # status_code: 200 - # transfer_size: 300 - # encoded_body_size: 356.9 - # decoded_body_size: 401.9 - # headers: - # content-type: application/json - # headers_sent: true - # finished: true - # user: - # id: '99' - # username: foo - # email: foo@mail.com - # tags: - # organization_uuid: 9f0e9d64-c185-4d21-a6f4-4673ed561ec8 - # tag5: null - # custom: - # my_key: 1 - # some_other_value: foobar - # and_objects: - # foo: - # - bar - # - baz - # (: notavalidregexandthatisfine diff --git a/docs/spec/openapi/bundled.json b/docs/spec/openapi/bundled.json index 75764ed9282..db24a1f41ab 100644 --- a/docs/spec/openapi/bundled.json +++ b/docs/spec/openapi/bundled.json @@ -36,6 +36,16 @@ "description": "The events intake API is the internal protocol that APM agents use to talk to the APM Server.", "x-displayName": "APM event intake" }, + { + "name": "jaeger intake", + "description": "Elastic APM natively supports Jaeger, an open-source, distributed tracing system.\n", + "x-displayName": "Jaeger event intake" + }, + { + "name": "opentelemetry intake", + "description": "The OpenTelemetry intake API uses the OpenTelemetry Protocol (OTLP) to send traces, metrics, and logs to APM Server. OTLP is the default transfer protocol for OpenTelemetry and is supported natively by APM Server. APM Server supports two OTLP communication protocols on the same port: OTLP/HTTP (protobuf) and OTLP/gRPC.\n", + "x-displayName": "APM OpenTelemetry intake" + }, { "name": "server info", "description": "APIs that query general APM Server information.", @@ -221,16 +231,6 @@ "tags": [ "event intake" ], - "parameters": [ - { - "in": "query", - "name": "async", - "description": "Indicates whether to use asynchronous processing, which is supported by APM Server in 8.5.0 and later. NOTE: Since asynchronous processing defers some of the event processing to the background and takes place after the client has closed the request, some errors can't be communicated back to the client and are logged by the APM Server. Furthermore, asynchronous processing requests will only be scheduled if the APM Server can service the incoming request; requests that cannot be serviced will receive an internal error 503 \"queue is full\" error.\n", - "schema": { - "type": "boolean" - } - } - ], "requestBody": { "content": { "application/ndjson": { @@ -347,127 +347,254 @@ } } } - } - }, - "components": { - "securitySchemes": { - "apiKeyAuth": { - "type": "apiKey", - "in": "header", - "name": "Authorization", - "description": "e.g. Authorization: ApiKey base64AccessApiKey" - }, - "secretToken": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "Secret token" - } }, - "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.\n", - "required": [ - "error" + "/jaeger.api_v2.CollectorService/PostSpans": { + "post": { + "summary": "Send Jaeger spans", + "deprecated": true, + "description": "APM Server supports receiving Jaeger spans. This API uses the gRPC protocol.\n", + "operationId": "postJaegerSpans", + "tags": [ + "jaeger intake" ], - "properties": { - "error": { - "$ref": "#/components/schemas/error" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" } } - }, - "ErrorEventv3": { - "type": "object", - "required": [ - "error" + } + }, + "/jaeger.api_v2.SamplingManager/GetSamplingStrategy": { + "get": { + "summary": "Get Jaeger sampling strategy", + "deprecated": true, + "description": "This API polls the APM Server for the sampling rate.\n", + "operationId": "getJaegerSampling", + "tags": [ + "jaeger intake" ], - "properties": { - "error": { - "$ref": "#/components/schemas/error-2" + "responses": { + "200": { + "description": "A successful response", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } } } - }, - "MetadataEvent": { - "type": "object", - "description": "Every new connection to the APM Server starts with a metadata stanza. This provides general metadata concerning the other objects in the stream. Rather than send this metadata information from the agent multiple times, the APM Server hangs on to this information and applies it to other objects in the stream as necessary. TIP: Metadata is stored under context when viewing documents in Elasticsearch. APM agents automatically read Kubernetes data and send it to the APM Server. In most instances, agents are able to read this data from inside the container. If this is not the case, or if you wish to override this data, you can set environment variables for the agents to read. These environment variable are set via the Kubernetes Downward API. \n", - "required": [ - "metadata" + } + }, + "/opentelemetry.proto.collector.metrics.v1.MetricsService/Export": { + "post": { + "summary": "Send OTLP metrics", + "description": "APM Server supports receiving metrics over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/gRPC communication protocol.\n", + "operationId": "postOtlpGrpcMetrics", + "tags": [ + "opentelemetry intake" ], - "properties": { - "metadata": { - "$ref": "#/components/schemas/metadata" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" } } - }, - "MetadataEventv3": { - "type": "object", - "required": [ - "metadata" + } + }, + "/opentelemetry.proto.collector.trace.v1.TraceService/Export": { + "post": { + "summary": "Send OTLP traces", + "description": "APM Server supports receiving traces over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/gRPC communication protocol.\n", + "operationId": "postOtlpGrpcTraces", + "tags": [ + "opentelemetry intake" ], - "properties": { - "metadata": { - "$ref": "#/components/schemas/metadata-2" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" } } - }, - "MetricSetEvent": { - "type": "object", - "description": "Metric sets are events that contain application metric data captured by an APM agent. \n", - "required": [ - "metricset" + } + }, + "/opentelemetry.proto.collector.logs.v1.LogsService/Export": { + "post": { + "summary": "Send OTLP logs", + "description": "APM Server supports receiving logs over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/gRPC communication protocol.\n", + "operationId": "postOtlpGrpcLogs", + "tags": [ + "opentelemetry intake" ], - "properties": { - "metricset": { - "$ref": "#/components/schemas/metricset" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" } } - }, - "SpanEvent": { - "type": "object", - "description": "Spans are events captured by an agent occurring in a monitored service.\n", - "required": [ - "span" + } + }, + "/v1/metrics": { + "post": { + "summary": "Send OTLP metrics", + "description": "APM Server supports receiving metrics over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/HTTP (protobuf) communication protocol.\n", + "operationId": "postOtlpHttpMetrics", + "tags": [ + "opentelemetry intake" ], - "properties": { - "span": { - "$ref": "#/components/schemas/span" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" } } - }, - "SpanEventv3": { - "type": "object", - "required": [ - "span" + } + }, + "/v1/traces": { + "post": { + "summary": "Send OTLP traces", + "description": "APM Server supports receiving traces over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/HTTP (protobuf) communication protocol.\n", + "operationId": "postOtlpHttpTraces", + "tags": [ + "opentelemetry intake" ], - "properties": { - "span": { - "$ref": "#/components/schemas/span-2" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" } } - }, - "TransactionEvent": { - "type": "object", - "description": "Transactions are events corresponding to an incoming request or similar task occurring in a monitored service.\n", - "required": [ - "transaction" + } + }, + "/v1/logs": { + "post": { + "summary": "Send OTLP logs", + "description": "APM Server supports receiving logs over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/HTTP (protobuf) communication protocol.\n", + "operationId": "postOtlpHttpLogs", + "tags": [ + "opentelemetry intake" ], - "properties": { - "transaction": { - "$ref": "#/components/schemas/transaction" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" } } + } + } + }, + "components": { + "securitySchemes": { + "apiKeyAuth": { + "type": "apiKey", + "in": "header", + "name": "Authorization", + "description": "e.g. Authorization: ApiKey base64AccessApiKey" }, - "TransactionEventv3": { - "type": "object", - "required": [ - "transaction" - ], - "properties": { - "transaction": { - "$ref": "#/components/schemas/transaction-2" + "secretToken": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "Secret token" + } + }, + "responses": { + "200_server_info": { + "description": "A successful response indicates that the server is up.", + "content": { + "application/json": { + "schema": { + "description": "If an API key or a secret token is passed along with the request, the response payload includes some information about the APM server.", + "type": "object", + "properties": { + "build_date": { + "type": "string", + "format": "time-date" + }, + "build_sha": { + "type": "string" + }, + "publish_ready": { + "type": "boolean" + }, + "version": { + "type": "string" + } + } + }, + "examples": { + "getServerHealthAuthResponse": { + "summary": "Example APM Server information request with a secret token", + "value": { + "build_date": "2021-12-18T19:59:06Z", + "build_sha": "24fe620eeff5a19e2133c940c7e5ce1ceddb1445", + "publish_ready": true, + "version": "8.12.2" + } + } + } } } - }, + } + }, + "schemas": { "error": { "$id": "docs/spec/v2/error", "description": "errorEvent represents an error or a logged error message, captured by an APM agent in a monitored service.", @@ -1761,6 +1888,18 @@ } ] }, + "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.\n", + "required": [ + "error" + ], + "properties": { + "error": { + "$ref": "#/components/schemas/error" + } + } + }, "metadata": { "$id": "docs/spec/v2/metadata", "type": "object", @@ -2336,6 +2475,18 @@ "service" ] }, + "MetadataEvent": { + "type": "object", + "description": "Every new connection to the APM Server starts with a metadata stanza. This provides general metadata concerning the other objects in the stream. Rather than send this metadata information from the agent multiple times, the APM Server hangs on to this information and applies it to other objects in the stream as necessary. TIP: Metadata is stored under context when viewing documents in Elasticsearch. APM agents automatically read Kubernetes data and send it to the APM Server. In most instances, agents are able to read this data from inside the container. If this is not the case, or if you wish to override this data, you can set environment variables for the agents to read. These environment variable are set via the Kubernetes Downward API. \n", + "required": [ + "metadata" + ], + "properties": { + "metadata": { + "$ref": "#/components/schemas/metadata" + } + } + }, "metricset": { "$id": "docs/spec/v2/metricset", "type": "object", @@ -2637,6 +2788,18 @@ "samples" ] }, + "MetricSetEvent": { + "type": "object", + "description": "Metric sets are events that contain application metric data captured by an APM agent. \n", + "required": [ + "metricset" + ], + "properties": { + "metricset": { + "$ref": "#/components/schemas/metricset" + } + } + }, "span": { "$id": "docs/spec/v2/span", "type": "object", @@ -3540,6 +3703,18 @@ } ] }, + "SpanEvent": { + "type": "object", + "description": "Spans are events captured by an agent occurring in a monitored service.\n", + "required": [ + "span" + ], + "properties": { + "span": { + "$ref": "#/components/schemas/span" + } + } + }, "transaction": { "$id": "docs/spec/v2/transaction", "type": "object", @@ -4671,6 +4846,18 @@ "duration" ] }, + "TransactionEvent": { + "type": "object", + "description": "Transactions are events corresponding to an incoming request or similar task occurring in a monitored service.\n", + "required": [ + "transaction" + ], + "properties": { + "transaction": { + "$ref": "#/components/schemas/transaction" + } + } + }, "error-2": { "$id": "docs/spec/rumv3/error", "type": "object", @@ -5518,6 +5705,17 @@ } ] }, + "ErrorEventv3": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "$ref": "#/components/schemas/error-2" + } + } + }, "metadata-2": { "$id": "docs/spec/rumv3/metadata", "type": "object", @@ -5736,6 +5934,17 @@ "se" ] }, + "MetadataEventv3": { + "type": "object", + "required": [ + "metadata" + ], + "properties": { + "metadata": { + "$ref": "#/components/schemas/metadata-2" + } + } + }, "span-2": { "$id": "docs/spec/rumv3/span", "type": "object", @@ -6100,6 +6309,17 @@ "d" ] }, + "SpanEventv3": { + "type": "object", + "required": [ + "span" + ], + "properties": { + "span": { + "$ref": "#/components/schemas/span-2" + } + } + }, "transaction-2": { "$id": "docs/spec/rumv3/transaction", "type": "object", @@ -7098,43 +7318,15 @@ "yc", "d" ] - } - }, - "responses": { - "200_server_info": { - "description": "A successful response indicates that the server is up.", - "content": { - "application/json": { - "schema": { - "description": "If an API key or a secret token is passed along with the request, the response payload includes some information about the APM server.", - "type": "object", - "properties": { - "build_date": { - "type": "string", - "format": "time-date" - }, - "build_sha": { - "type": "string" - }, - "publish_ready": { - "type": "boolean" - }, - "version": { - "type": "string" - } - } - }, - "examples": { - "getServerHealthAuthResponse": { - "summary": "Example APM Server information request with a secret token", - "value": { - "build_date": "2021-12-18T19:59:06Z", - "build_sha": "24fe620eeff5a19e2133c940c7e5ce1ceddb1445", - "publish_ready": true, - "version": "8.12.2" - } - } - } + }, + "TransactionEventv3": { + "type": "object", + "required": [ + "transaction" + ], + "properties": { + "transaction": { + "$ref": "#/components/schemas/transaction-2" } } } diff --git a/docs/spec/openapi/bundled.yaml b/docs/spec/openapi/bundled.yaml index 0dcdffe0b13..80842a9740e 100644 --- a/docs/spec/openapi/bundled.yaml +++ b/docs/spec/openapi/bundled.yaml @@ -20,6 +20,14 @@ 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 + - name: jaeger intake + description: | + Elastic APM natively supports Jaeger, an open-source, distributed tracing system. + x-displayName: Jaeger event intake + - name: opentelemetry intake + description: | + The OpenTelemetry intake API uses the OpenTelemetry Protocol (OTLP) to send traces, metrics, and logs to APM Server. OTLP is the default transfer protocol for OpenTelemetry and is supported natively by APM Server. APM Server supports two OTLP communication protocols on the same port: OTLP/HTTP (protobuf) and OTLP/gRPC. + x-displayName: APM OpenTelemetry intake - name: server info description: APIs that query general APM Server information. x-displayName: APM server information @@ -153,13 +161,6 @@ paths: operationId: postEventIntake tags: - event intake - parameters: - - in: query - name: async - description: | - Indicates whether to use asynchronous processing, which is supported by APM Server in 8.5.0 and later. NOTE: Since asynchronous processing defers some of the event processing to the background and takes place after the client has closed the request, some errors can't be communicated back to the client and are logged by the APM Server. Furthermore, asynchronous processing requests will only be scheduled if the APM Server can service the incoming request; requests that cannot be serviced will receive an internal error 503 "queue is full" error. - schema: - type: boolean requestBody: content: application/ndjson: @@ -219,6 +220,135 @@ paths: responses: '202': description: Successful response; all events succeeded. + /jaeger.api_v2.CollectorService/PostSpans: + post: + summary: Send Jaeger spans + deprecated: true + description: | + APM Server supports receiving Jaeger spans. This API uses the gRPC protocol. + operationId: postJaegerSpans + tags: + - jaeger intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK + /jaeger.api_v2.SamplingManager/GetSamplingStrategy: + get: + summary: Get Jaeger sampling strategy + deprecated: true + description: | + This API polls the APM Server for the sampling rate. + operationId: getJaegerSampling + tags: + - jaeger intake + responses: + '200': + description: A successful response + content: + application/json: + schema: + type: object + /opentelemetry.proto.collector.metrics.v1.MetricsService/Export: + post: + summary: Send OTLP metrics + description: | + APM Server supports receiving metrics over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/gRPC communication protocol. + operationId: postOtlpGrpcMetrics + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK + /opentelemetry.proto.collector.trace.v1.TraceService/Export: + post: + summary: Send OTLP traces + description: | + APM Server supports receiving traces over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/gRPC communication protocol. + operationId: postOtlpGrpcTraces + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK + /opentelemetry.proto.collector.logs.v1.LogsService/Export: + post: + summary: Send OTLP logs + description: | + APM Server supports receiving logs over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/gRPC communication protocol. + operationId: postOtlpGrpcLogs + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK + /v1/metrics: + post: + summary: Send OTLP metrics + description: | + APM Server supports receiving metrics over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/HTTP (protobuf) communication protocol. + operationId: postOtlpHttpMetrics + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK + /v1/traces: + post: + summary: Send OTLP traces + description: | + APM Server supports receiving traces over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/HTTP (protobuf) communication protocol. + operationId: postOtlpHttpTraces + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK + /v1/logs: + post: + summary: Send OTLP logs + description: | + APM Server supports receiving logs over the OpenTelemetry Protocol (OTLP). This API uses the OTLP/HTTP (protobuf) communication protocol. + operationId: postOtlpHttpLogs + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK components: securitySchemes: apiKeyAuth: @@ -230,80 +360,33 @@ components: type: http scheme: bearer bearerFormat: Secret token + responses: + 200_server_info: + description: A successful response indicates that the server is up. + content: + application/json: + schema: + description: If an API key or a secret token is passed along with the request, the response payload includes some information about the APM server. + type: object + properties: + build_date: + type: string + format: time-date + build_sha: + type: string + publish_ready: + type: boolean + version: + type: string + examples: + getServerHealthAuthResponse: + summary: Example APM Server information request with a secret token + value: + build_date: '2021-12-18T19:59:06Z' + build_sha: 24fe620eeff5a19e2133c940c7e5ce1ceddb1445 + publish_ready: true + version: 8.12.2 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' - ErrorEventv3: - type: object - required: - - error - properties: - error: - $ref: '#/components/schemas/error-2' - MetadataEvent: - type: object - description: | - Every new connection to the APM Server starts with a metadata stanza. This provides general metadata concerning the other objects in the stream. Rather than send this metadata information from the agent multiple times, the APM Server hangs on to this information and applies it to other objects in the stream as necessary. TIP: Metadata is stored under context when viewing documents in Elasticsearch. APM agents automatically read Kubernetes data and send it to the APM Server. In most instances, agents are able to read this data from inside the container. If this is not the case, or if you wish to override this data, you can set environment variables for the agents to read. These environment variable are set via the Kubernetes Downward API. - required: - - metadata - properties: - metadata: - $ref: '#/components/schemas/metadata' - MetadataEventv3: - type: object - required: - - metadata - properties: - metadata: - $ref: '#/components/schemas/metadata-2' - MetricSetEvent: - type: object - description: | - Metric sets are events that contain application metric data captured by an APM agent. - required: - - metricset - properties: - metricset: - $ref: '#/components/schemas/metricset' - SpanEvent: - type: object - description: | - Spans are events captured by an agent occurring in a monitored service. - required: - - span - properties: - span: - $ref: '#/components/schemas/span' - SpanEventv3: - type: object - required: - - span - properties: - span: - $ref: '#/components/schemas/span-2' - TransactionEvent: - type: object - description: | - Transactions are events corresponding to an incoming request or similar task occurring in a monitored service. - required: - - transaction - properties: - transaction: - $ref: '#/components/schemas/transaction' - TransactionEventv3: - type: object - required: - - transaction - properties: - transaction: - $ref: '#/components/schemas/transaction-2' error: $id: docs/spec/v2/error description: errorEvent represents an error or a logged error message, captured by an APM agent in a monitored service. @@ -1191,6 +1274,15 @@ components: type: object required: - log + 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' metadata: $id: docs/spec/v2/metadata type: object @@ -1607,6 +1699,15 @@ components: maxLength: 1024 required: - service + MetadataEvent: + type: object + description: | + Every new connection to the APM Server starts with a metadata stanza. This provides general metadata concerning the other objects in the stream. Rather than send this metadata information from the agent multiple times, the APM Server hangs on to this information and applies it to other objects in the stream as necessary. TIP: Metadata is stored under context when viewing documents in Elasticsearch. APM agents automatically read Kubernetes data and send it to the APM Server. In most instances, agents are able to read this data from inside the container. If this is not the case, or if you wish to override this data, you can set environment variables for the agents to read. These environment variable are set via the Kubernetes Downward API. + required: + - metadata + properties: + metadata: + $ref: '#/components/schemas/metadata' metricset: $id: docs/spec/v2/metricset type: object @@ -1809,6 +1910,15 @@ components: maxLength: 1024 required: - samples + MetricSetEvent: + type: object + description: | + Metric sets are events that contain application metric data captured by an APM agent. + required: + - metricset + properties: + metricset: + $ref: '#/components/schemas/metricset' span: $id: docs/spec/v2/span type: object @@ -2445,6 +2555,15 @@ components: type: integer required: - timestamp + SpanEvent: + type: object + description: | + Spans are events captured by an agent occurring in a monitored service. + required: + - span + properties: + span: + $ref: '#/components/schemas/span' transaction: $id: docs/spec/v2/transaction type: object @@ -3253,6 +3372,15 @@ components: - type - span_count - duration + TransactionEvent: + type: object + description: | + Transactions are events corresponding to an incoming request or similar task occurring in a monitored service. + required: + - transaction + properties: + transaction: + $ref: '#/components/schemas/transaction' error-2: $id: docs/spec/rumv3/error type: object @@ -3837,6 +3965,13 @@ components: type: object required: - log + ErrorEventv3: + type: object + required: + - error + properties: + error: + $ref: '#/components/schemas/error-2' metadata-2: $id: docs/spec/rumv3/metadata type: object @@ -3996,6 +4131,13 @@ components: maxLength: 1024 required: - se + MetadataEventv3: + type: object + required: + - metadata + properties: + metadata: + $ref: '#/components/schemas/metadata-2' span-2: $id: docs/spec/rumv3/span type: object @@ -4260,6 +4402,13 @@ components: - id - s - d + SpanEventv3: + type: object + required: + - span + properties: + span: + $ref: '#/components/schemas/span-2' transaction-2: $id: docs/spec/rumv3/transaction type: object @@ -4982,32 +5131,13 @@ components: - id - yc - d - responses: - 200_server_info: - description: A successful response indicates that the server is up. - content: - application/json: - schema: - description: If an API key or a secret token is passed along with the request, the response payload includes some information about the APM server. - type: object - properties: - build_date: - type: string - format: time-date - build_sha: - type: string - publish_ready: - type: boolean - version: - type: string - examples: - getServerHealthAuthResponse: - summary: Example APM Server information request with a secret token - value: - build_date: '2021-12-18T19:59:06Z' - build_sha: 24fe620eeff5a19e2133c940c7e5ce1ceddb1445 - publish_ready: true - version: 8.12.2 + TransactionEventv3: + type: object + required: + - transaction + properties: + transaction: + $ref: '#/components/schemas/transaction-2' examples: metadataEventIntakeRequestExample: summary: A request body example for the metadata event type. diff --git a/docs/spec/openapi/components/examples/metadataEventIntakeRequestExample.yaml b/docs/spec/openapi/components/examples/metadataEventIntakeRequestExample.yaml new file mode 100644 index 00000000000..7f083bf5f01 --- /dev/null +++ b/docs/spec/openapi/components/examples/metadataEventIntakeRequestExample.yaml @@ -0,0 +1,46 @@ +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 diff --git a/docs/spec/openapi/components/examples/metricSetEventIntakeRequestExample.yaml b/docs/spec/openapi/components/examples/metricSetEventIntakeRequestExample.yaml new file mode 100644 index 00000000000..488068a4441 --- /dev/null +++ b/docs/spec/openapi/components/examples/metricSetEventIntakeRequestExample.yaml @@ -0,0 +1,44 @@ +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 diff --git a/docs/spec/openapi/components/responses/200_server_info.yaml b/docs/spec/openapi/components/responses/200_server_info.yaml new file mode 100644 index 00000000000..6e59a15f95e --- /dev/null +++ b/docs/spec/openapi/components/responses/200_server_info.yaml @@ -0,0 +1,26 @@ +description: A successful response indicates that the server is up. +content: + application/json: + schema: + description: >- + If an API key or a secret token is passed along with the request, the + response payload includes some information about the APM server. + type: object + properties: + build_date: + type: string + format: time-date + build_sha: + type: string + publish_ready: + type: boolean + version: + type: string + examples: + getServerHealthAuthResponse: + summary: Example APM Server information request with a secret token + value: + build_date: '2021-12-18T19:59:06Z' + build_sha: 24fe620eeff5a19e2133c940c7e5ce1ceddb1445 + publish_ready: true + version: 8.12.2 diff --git a/docs/spec/openapi/components/schemas/ErrorEvent.yaml b/docs/spec/openapi/components/schemas/ErrorEvent.yaml new file mode 100644 index 00000000000..ba5ed10d423 --- /dev/null +++ b/docs/spec/openapi/components/schemas/ErrorEvent.yaml @@ -0,0 +1,9 @@ +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: ../../../v2/error.json diff --git a/docs/spec/openapi/components/schemas/ErrorEventv3.yaml b/docs/spec/openapi/components/schemas/ErrorEventv3.yaml new file mode 100644 index 00000000000..750eeee1933 --- /dev/null +++ b/docs/spec/openapi/components/schemas/ErrorEventv3.yaml @@ -0,0 +1,6 @@ +type: object +required: + - error +properties: + error: + $ref: ../../../rumv3/error.json diff --git a/docs/spec/openapi/components/schemas/MetadataEvent.yaml b/docs/spec/openapi/components/schemas/MetadataEvent.yaml new file mode 100644 index 00000000000..e9bfac9737c --- /dev/null +++ b/docs/spec/openapi/components/schemas/MetadataEvent.yaml @@ -0,0 +1,17 @@ +type: object +description: > + Every new connection to the APM Server starts with a metadata stanza. This + provides general metadata concerning the other objects in the stream. Rather + than send this metadata information from the agent multiple times, the APM + Server hangs on to this information and applies it to other objects in the + stream as necessary. TIP: Metadata is stored under context when viewing + documents in Elasticsearch. APM agents automatically read Kubernetes data and + send it to the APM Server. In most instances, agents are able to read this + data from inside the container. If this is not the case, or if you wish to + override this data, you can set environment variables for the agents to read. + These environment variable are set via the Kubernetes Downward API. +required: + - metadata +properties: + metadata: + $ref: ../../../v2/metadata.json diff --git a/docs/spec/openapi/components/schemas/MetadataEventv3.yaml b/docs/spec/openapi/components/schemas/MetadataEventv3.yaml new file mode 100644 index 00000000000..b6f129244c6 --- /dev/null +++ b/docs/spec/openapi/components/schemas/MetadataEventv3.yaml @@ -0,0 +1,6 @@ +type: object +required: + - metadata +properties: + metadata: + $ref: ../../../rumv3/metadata.json diff --git a/docs/spec/openapi/components/schemas/MetricSetEvent.yaml b/docs/spec/openapi/components/schemas/MetricSetEvent.yaml new file mode 100644 index 00000000000..e1d48231ff0 --- /dev/null +++ b/docs/spec/openapi/components/schemas/MetricSetEvent.yaml @@ -0,0 +1,9 @@ +type: object +description: > + Metric sets are events that contain application metric data captured by an APM + agent. +required: + - metricset +properties: + metricset: + $ref: ../../../v2/metricset.json diff --git a/docs/spec/openapi/components/schemas/SpanEvent.yaml b/docs/spec/openapi/components/schemas/SpanEvent.yaml new file mode 100644 index 00000000000..cb144f74a73 --- /dev/null +++ b/docs/spec/openapi/components/schemas/SpanEvent.yaml @@ -0,0 +1,8 @@ +type: object +description: | + Spans are events captured by an agent occurring in a monitored service. +required: + - span +properties: + span: + $ref: ../../../v2/span.json diff --git a/docs/spec/openapi/components/schemas/SpanEventv3.yaml b/docs/spec/openapi/components/schemas/SpanEventv3.yaml new file mode 100644 index 00000000000..6517ee91ab9 --- /dev/null +++ b/docs/spec/openapi/components/schemas/SpanEventv3.yaml @@ -0,0 +1,6 @@ +type: object +required: + - span +properties: + span: + $ref: ../../../rumv3/span.json diff --git a/docs/spec/openapi/components/schemas/TransactionEvent.yaml b/docs/spec/openapi/components/schemas/TransactionEvent.yaml new file mode 100644 index 00000000000..fc3e89cddfb --- /dev/null +++ b/docs/spec/openapi/components/schemas/TransactionEvent.yaml @@ -0,0 +1,9 @@ +type: object +description: > + Transactions are events corresponding to an incoming request or similar task + occurring in a monitored service. +required: + - transaction +properties: + transaction: + $ref: ../../../v2/transaction.json diff --git a/docs/spec/openapi/components/schemas/TransactionEventv3.yaml b/docs/spec/openapi/components/schemas/TransactionEventv3.yaml new file mode 100644 index 00000000000..11fed7b6ed1 --- /dev/null +++ b/docs/spec/openapi/components/schemas/TransactionEventv3.yaml @@ -0,0 +1,6 @@ +type: object +required: + - transaction +properties: + transaction: + $ref: ../../../rumv3/transaction.json diff --git a/docs/spec/openapi/paths/config_v1_agents.yaml b/docs/spec/openapi/paths/config_v1_agents.yaml new file mode 100644 index 00000000000..0b4aee7e615 --- /dev/null +++ b/docs/spec/openapi/paths/config_v1_agents.yaml @@ -0,0 +1,105 @@ +get: + summary: Get agent configuration changes + description: > + To configure authenticated access to the APM server, the instructions at + [APM API + key](https://www.elastic.co/guide/en/observability/current/api-key.html) or + [APM Secret + Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) + must be followed to configure the correct permissions for APM access. + operationId: getAgentConfig + tags: + - agent config + parameters: + - in: query + name: service.name + required: true + schema: + type: string + - in: query + name: service.environment + schema: + type: string + responses: + '200': + description: A successful response. + content: + application/json: + schema: + type: object +post: + summary: Get agent configuration changes + description: > + To configure authenticated access to the APM server, the instructions at + [APM API + key](https://www.elastic.co/guide/en/observability/current/api-key.html) or + [APM Secret + Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) + must be followed to configure the correct permissions for APM access. + operationId: postAgentConfig + tags: + - agent config + requestBody: + content: + application/json: + schema: + type: object + required: + - service + properties: + CAPTURE_BODY: + type: string + example: 'off' + service: + type: object + required: + - name + properties: + environment: + type: string + example: all + name: + type: string + example: test-service + additionalProperties: true + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: object + properties: + capture_body: + type: string + enum: + - 'off' + - errors + - transactions + - all + description: > + For transactions that are HTTP requests, the agent can + optionally capture the request body (for example, POST + variables). For transactions that are initiated by receiving a + message from a message broker, the agent can capture the + textual message body. + example: 'off' + transaction_max_spans: + type: integer + minimum: 0 + description: The maximum number of spans that are recorded per transaction. + example: 500 + transaction_sample_rate: + type: number + format: float + minimum: 0 + maximum: 1 + description: The agent samples transactions at this rate. + example: 0.3 + additionalProperties: true + '403': + description: >- + APM Server is configured to fetch agent configuration from Elasticsearch + but the configuration is invalid. + '503': + description: APM Server is starting up or Elasticsearch is unreachable. diff --git a/docs/spec/openapi/paths/config_v1_rum_agents.yaml b/docs/spec/openapi/paths/config_v1_rum_agents.yaml new file mode 100644 index 00000000000..b6de6a79154 --- /dev/null +++ b/docs/spec/openapi/paths/config_v1_rum_agents.yaml @@ -0,0 +1,15 @@ +get: + summary: Get RUM agent configuration changes + description: > + To configure authenticated access to the APM server, the instructions at + [APM API + key](https://www.elastic.co/guide/en/observability/current/api-key.html) or + [APM Secret + Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) + must be followed to configure the correct permissions for APM access. + operationId: getRumAgentConfig + tags: + - agent config + responses: + '200': + description: Successful response. diff --git a/docs/spec/openapi/paths/intake_v2_events.yaml b/docs/spec/openapi/paths/intake_v2_events.yaml new file mode 100644 index 00000000000..e9da3077ea2 --- /dev/null +++ b/docs/spec/openapi/paths/intake_v2_events.yaml @@ -0,0 +1,37 @@ +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.yaml + - $ref: ../components/schemas/MetadataEvent.yaml + - $ref: ../components/schemas/MetricSetEvent.yaml + - $ref: ../components/schemas/SpanEvent.yaml + - $ref: ../components/schemas/TransactionEvent.yaml + examples: + postMetadataEventIntakeExample: + $ref: ../components/examples/metadataEventIntakeRequestExample.yaml + postMetricSetEventIntakeExample: + $ref: ../components/examples/metricSetEventIntakeRequestExample.yaml + responses: + '202': + description: Successful response; all events succeeded. diff --git a/docs/spec/openapi/paths/intake_v2_rum_events.yaml b/docs/spec/openapi/paths/intake_v2_rum_events.yaml new file mode 100644 index 00000000000..15937aaf989 --- /dev/null +++ b/docs/spec/openapi/paths/intake_v2_rum_events.yaml @@ -0,0 +1,21 @@ +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.yaml + - $ref: ../components/schemas/MetadataEvent.yaml + - $ref: ../components/schemas/MetricSetEvent.yaml + - $ref: ../components/schemas/SpanEvent.yaml + - $ref: ../components/schemas/TransactionEvent.yaml + responses: + '202': + description: Successful response; all events succeeded. diff --git a/docs/spec/openapi/paths/intake_v3_rum_events.yaml b/docs/spec/openapi/paths/intake_v3_rum_events.yaml new file mode 100644 index 00000000000..2ded9f14929 --- /dev/null +++ b/docs/spec/openapi/paths/intake_v3_rum_events.yaml @@ -0,0 +1,20 @@ +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.yaml + - $ref: ../components/schemas/MetadataEventv3.yaml + - $ref: ../components/schemas/SpanEventv3.yaml + - $ref: ../components/schemas/TransactionEventv3.yaml + responses: + '202': + description: Successful response; all events succeeded. diff --git a/docs/spec/openapi/paths/jaeger.api_v2.CollectorService_PostSpans.yaml b/docs/spec/openapi/paths/jaeger.api_v2.CollectorService_PostSpans.yaml new file mode 100644 index 00000000000..4b42cf4ca42 --- /dev/null +++ b/docs/spec/openapi/paths/jaeger.api_v2.CollectorService_PostSpans.yaml @@ -0,0 +1,16 @@ +post: + summary: Send Jaeger spans + deprecated: true + description: | + APM Server supports receiving Jaeger spans. This API uses the gRPC protocol. + operationId: postJaegerSpans + tags: + - jaeger intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK diff --git a/docs/spec/openapi/paths/jaeger.api_v2.SamplingManager_GetSamplingStrategy.yaml b/docs/spec/openapi/paths/jaeger.api_v2.SamplingManager_GetSamplingStrategy.yaml new file mode 100644 index 00000000000..0ca9546f841 --- /dev/null +++ b/docs/spec/openapi/paths/jaeger.api_v2.SamplingManager_GetSamplingStrategy.yaml @@ -0,0 +1,15 @@ +get: + summary: Get Jaeger sampling strategy + deprecated: true + description: | + This API polls the APM Server for the sampling rate. + operationId: getJaegerSampling + tags: + - jaeger intake + responses: + '200': + description: A successful response + content: + application/json: + schema: + type: object diff --git a/docs/spec/openapi/paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml b/docs/spec/openapi/paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml new file mode 100644 index 00000000000..c171bf72793 --- /dev/null +++ b/docs/spec/openapi/paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml @@ -0,0 +1,16 @@ +post: + summary: Send OTLP logs + description: > + APM Server supports receiving logs over the OpenTelemetry Protocol (OTLP). + This API uses the OTLP/gRPC communication protocol. + operationId: postOtlpGrpcLogs + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK diff --git a/docs/spec/openapi/paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml b/docs/spec/openapi/paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml new file mode 100644 index 00000000000..9102f8aa21f --- /dev/null +++ b/docs/spec/openapi/paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml @@ -0,0 +1,16 @@ +post: + summary: Send OTLP metrics + description: > + APM Server supports receiving metrics over the OpenTelemetry Protocol + (OTLP). This API uses the OTLP/gRPC communication protocol. + operationId: postOtlpGrpcMetrics + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK diff --git a/docs/spec/openapi/paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml b/docs/spec/openapi/paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml new file mode 100644 index 00000000000..2e22e2d9fff --- /dev/null +++ b/docs/spec/openapi/paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml @@ -0,0 +1,16 @@ +post: + summary: Send OTLP traces + description: > + APM Server supports receiving traces over the OpenTelemetry Protocol (OTLP). + This API uses the OTLP/gRPC communication protocol. + operationId: postOtlpGrpcTraces + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK diff --git a/docs/spec/openapi/paths/server_info.yaml b/docs/spec/openapi/paths/server_info.yaml new file mode 100644 index 00000000000..a70149acfce --- /dev/null +++ b/docs/spec/openapi/paths/server_info.yaml @@ -0,0 +1,25 @@ +get: + summary: Get general server information + description: > + This lightweight endpoint is useful as a server up/down health check. + + To configure authenticated access to the APM server, the instructions at + [APM API + key](https://www.elastic.co/guide/en/observability/current/api-key.html) or + [APM Secret + Token](https://www.elastic.co/guide/en/observability/current/secret-token.html) + must be followed to configure the correct permissions for APM access. + operationId: getServerHealth + tags: + - server info + responses: + '200': + $ref: '../components/responses/200_server_info.yaml' +post: + summary: Get general server information + operationId: postServerHealth + tags: + - server info + responses: + '200': + $ref: '../components/responses/200_server_info.yaml' diff --git a/docs/spec/openapi/paths/v1_logs.yaml b/docs/spec/openapi/paths/v1_logs.yaml new file mode 100644 index 00000000000..fbfa7922690 --- /dev/null +++ b/docs/spec/openapi/paths/v1_logs.yaml @@ -0,0 +1,16 @@ +post: + summary: Send OTLP logs + description: > + APM Server supports receiving logs over the OpenTelemetry Protocol (OTLP). + This API uses the OTLP/HTTP (protobuf) communication protocol. + operationId: postOtlpHttpLogs + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK diff --git a/docs/spec/openapi/paths/v1_metrics.yaml b/docs/spec/openapi/paths/v1_metrics.yaml new file mode 100644 index 00000000000..b1abde3b802 --- /dev/null +++ b/docs/spec/openapi/paths/v1_metrics.yaml @@ -0,0 +1,16 @@ +post: + summary: Send OTLP metrics + description: > + APM Server supports receiving metrics over the OpenTelemetry Protocol + (OTLP). This API uses the OTLP/HTTP (protobuf) communication protocol. + operationId: postOtlpHttpMetrics + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK diff --git a/docs/spec/openapi/paths/v1_traces.yaml b/docs/spec/openapi/paths/v1_traces.yaml new file mode 100644 index 00000000000..fb8103f67ed --- /dev/null +++ b/docs/spec/openapi/paths/v1_traces.yaml @@ -0,0 +1,16 @@ +post: + summary: Send OTLP traces + description: > + APM Server supports receiving traces over the OpenTelemetry Protocol (OTLP). + This API uses the OTLP/HTTP (protobuf) communication protocol. + operationId: postOtlpHttpTraces + tags: + - opentelemetry intake + requestBody: + content: + application/json: + schema: + type: object + responses: + '200': + description: OK