From e6b5933d2427425a047e53dbe68491dc13b0fcea Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 25 Apr 2024 17:29:22 -0700 Subject: [PATCH 1/5] [DOCS] Add OpenTelemetry intake API to OpenAPI document --- docs/README.md | 8 ++ docs/spec/openapi/apm-openapi.yaml | 108 +++++++++++++++++++++ docs/spec/openapi/bundled.json | 149 +++++++++++++++++++++++++++++ docs/spec/openapi/bundled.yaml | 100 +++++++++++++++++++ 4 files changed, 365 insertions(+) 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..f9984d76f4d 100644 --- a/docs/spec/openapi/apm-openapi.yaml +++ b/docs/spec/openapi/apm-openapi.yaml @@ -20,6 +20,12 @@ 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: 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 @@ -225,6 +231,108 @@ paths: responses: '202': description: Successful response; all events succeeded. + /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: diff --git a/docs/spec/openapi/bundled.json b/docs/spec/openapi/bundled.json index 75764ed9282..a8bce65e422 100644 --- a/docs/spec/openapi/bundled.json +++ b/docs/spec/openapi/bundled.json @@ -36,6 +36,11 @@ "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": "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.", @@ -347,6 +352,150 @@ } } } + }, + "/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" + ], + "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.\n", + "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.\n", + "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.\n", + "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.\n", + "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.\n", + "operationId": "postOtlpHttpLogs", + "tags": [ + "opentelemetry intake" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "OK" + } + } + } } }, "components": { diff --git a/docs/spec/openapi/bundled.yaml b/docs/spec/openapi/bundled.yaml index 0dcdffe0b13..9f7b8966172 100644 --- a/docs/spec/openapi/bundled.yaml +++ b/docs/spec/openapi/bundled.yaml @@ -20,6 +20,10 @@ 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: 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 @@ -219,6 +223,102 @@ paths: responses: '202': description: Successful response; all events succeeded. + /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: From 9e37ac97185d1528510f600115cb14d4551c33d3 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 26 Apr 2024 14:02:41 -0700 Subject: [PATCH 2/5] Add Jaeger event intake APIs --- docs/spec/openapi/apm-openapi.yaml | 36 +++++++++++++++++++++ docs/spec/openapi/bundled.json | 51 ++++++++++++++++++++++++++++++ docs/spec/openapi/bundled.yaml | 35 ++++++++++++++++++++ 3 files changed, 122 insertions(+) diff --git a/docs/spec/openapi/apm-openapi.yaml b/docs/spec/openapi/apm-openapi.yaml index f9984d76f4d..b73ef9c2c68 100644 --- a/docs/spec/openapi/apm-openapi.yaml +++ b/docs/spec/openapi/apm-openapi.yaml @@ -20,6 +20,10 @@ 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. @@ -231,6 +235,38 @@ paths: responses: '202': description: Successful response; all events succeeded. + /jaeger.api_v2.CollectorService/PostSpans: + post: + summary: Send Jaeger spans + 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 + 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 diff --git a/docs/spec/openapi/bundled.json b/docs/spec/openapi/bundled.json index a8bce65e422..dd8a8fa87c3 100644 --- a/docs/spec/openapi/bundled.json +++ b/docs/spec/openapi/bundled.json @@ -36,6 +36,11 @@ "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", @@ -353,6 +358,52 @@ } } }, + "/jaeger.api_v2.CollectorService/PostSpans": { + "post": { + "summary": "Send Jaeger spans", + "description": "APM Server supports receiving Jaeger spans. This API uses the gRPC protocol.\n", + "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", + "description": "This API polls the APM Server for the sampling rate.\n", + "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", diff --git a/docs/spec/openapi/bundled.yaml b/docs/spec/openapi/bundled.yaml index 9f7b8966172..564f9d7aa5d 100644 --- a/docs/spec/openapi/bundled.yaml +++ b/docs/spec/openapi/bundled.yaml @@ -20,6 +20,10 @@ 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. @@ -223,6 +227,37 @@ paths: responses: '202': description: Successful response; all events succeeded. + /jaeger.api_v2.CollectorService/PostSpans: + post: + summary: Send Jaeger spans + 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 + 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 From c4024fde0efa01ff4a2795cf3497fddbfbb87c83 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 8 May 2024 11:45:29 -0700 Subject: [PATCH 3/5] Deprecate Jaeger operations --- docs/spec/openapi/apm-openapi.yaml | 2 ++ docs/spec/openapi/bundled.json | 2 ++ docs/spec/openapi/bundled.yaml | 2 ++ 3 files changed, 6 insertions(+) diff --git a/docs/spec/openapi/apm-openapi.yaml b/docs/spec/openapi/apm-openapi.yaml index b73ef9c2c68..44db28dfbc7 100644 --- a/docs/spec/openapi/apm-openapi.yaml +++ b/docs/spec/openapi/apm-openapi.yaml @@ -238,6 +238,7 @@ paths: /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. @@ -255,6 +256,7 @@ paths: /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 diff --git a/docs/spec/openapi/bundled.json b/docs/spec/openapi/bundled.json index dd8a8fa87c3..d8ed23e0ce8 100644 --- a/docs/spec/openapi/bundled.json +++ b/docs/spec/openapi/bundled.json @@ -361,6 +361,7 @@ "/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": [ @@ -385,6 +386,7 @@ "/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": [ diff --git a/docs/spec/openapi/bundled.yaml b/docs/spec/openapi/bundled.yaml index 564f9d7aa5d..ef635d8a6cd 100644 --- a/docs/spec/openapi/bundled.yaml +++ b/docs/spec/openapi/bundled.yaml @@ -230,6 +230,7 @@ paths: /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 @@ -246,6 +247,7 @@ paths: /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 From 87389bf72490eb279b4b8f4a25616643efda8692 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 13 May 2024 12:50:58 -0700 Subject: [PATCH 4/5] Split OpenAPI source files --- docs/spec/openapi/apm-openapi.yaml | 826 +----------------- docs/spec/openapi/bundled.json | 280 +++--- docs/spec/openapi/bundled.yaml | 198 ++--- .../metadataEventIntakeRequestExample.yaml | 46 + .../metricSetEventIntakeRequestExample.yaml | 44 + .../components/responses/200_server_info.yaml | 26 + .../components/schemas/ErrorEvent.yaml | 9 + .../components/schemas/ErrorEventv3.yaml | 6 + .../components/schemas/MetadataEvent.yaml | 17 + .../components/schemas/MetadataEventv3.yaml | 6 + .../components/schemas/MetricSetEvent.yaml | 9 + .../openapi/components/schemas/SpanEvent.yaml | 8 + .../components/schemas/SpanEventv3.yaml | 6 + .../components/schemas/TransactionEvent.yaml | 9 + .../schemas/TransactionEventv3.yaml | 6 + docs/spec/openapi/paths/config_v1_agents.yaml | 105 +++ .../openapi/paths/config_v1_rum_agents.yaml | 15 + docs/spec/openapi/paths/intake_v2_events.yaml | 51 ++ .../openapi/paths/intake_v2_rum_events.yaml | 21 + .../openapi/paths/intake_v3_rum_events.yaml | 20 + ...ger.api_v2.CollectorService_PostSpans.yaml | 16 + ...2.SamplingManager_GetSamplingStrategy.yaml | 15 + ....collector.logs.v1.LogsService_Export.yaml | 16 + ...ctor.metrics.v1.MetricsService_Export.yaml | 16 + ...ollector.trace.v1.TraceService_Export.yaml | 16 + docs/spec/openapi/paths/server_info.yaml | 25 + docs/spec/openapi/paths/v1_logs.yaml | 16 + docs/spec/openapi/paths/v1_metrics.yaml | 16 + docs/spec/openapi/paths/v1_traces.yaml | 16 + 29 files changed, 820 insertions(+), 1040 deletions(-) create mode 100644 docs/spec/openapi/components/examples/metadataEventIntakeRequestExample.yaml create mode 100644 docs/spec/openapi/components/examples/metricSetEventIntakeRequestExample.yaml create mode 100644 docs/spec/openapi/components/responses/200_server_info.yaml create mode 100644 docs/spec/openapi/components/schemas/ErrorEvent.yaml create mode 100644 docs/spec/openapi/components/schemas/ErrorEventv3.yaml create mode 100644 docs/spec/openapi/components/schemas/MetadataEvent.yaml create mode 100644 docs/spec/openapi/components/schemas/MetadataEventv3.yaml create mode 100644 docs/spec/openapi/components/schemas/MetricSetEvent.yaml create mode 100644 docs/spec/openapi/components/schemas/SpanEvent.yaml create mode 100644 docs/spec/openapi/components/schemas/SpanEventv3.yaml create mode 100644 docs/spec/openapi/components/schemas/TransactionEvent.yaml create mode 100644 docs/spec/openapi/components/schemas/TransactionEventv3.yaml create mode 100644 docs/spec/openapi/paths/config_v1_agents.yaml create mode 100644 docs/spec/openapi/paths/config_v1_rum_agents.yaml create mode 100644 docs/spec/openapi/paths/intake_v2_events.yaml create mode 100644 docs/spec/openapi/paths/intake_v2_rum_events.yaml create mode 100644 docs/spec/openapi/paths/intake_v3_rum_events.yaml create mode 100644 docs/spec/openapi/paths/jaeger.api_v2.CollectorService_PostSpans.yaml create mode 100644 docs/spec/openapi/paths/jaeger.api_v2.SamplingManager_GetSamplingStrategy.yaml create mode 100644 docs/spec/openapi/paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml create mode 100644 docs/spec/openapi/paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml create mode 100644 docs/spec/openapi/paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml create mode 100644 docs/spec/openapi/paths/server_info.yaml create mode 100644 docs/spec/openapi/paths/v1_logs.yaml create mode 100644 docs/spec/openapi/paths/v1_metrics.yaml create mode 100644 docs/spec/openapi/paths/v1_traces.yaml diff --git a/docs/spec/openapi/apm-openapi.yaml b/docs/spec/openapi/apm-openapi.yaml index 44db28dfbc7..d4a9a84db3f 100644 --- a/docs/spec/openapi/apm-openapi.yaml +++ b/docs/spec/openapi/apm-openapi.yaml @@ -18,359 +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 + 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. + 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: - 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 + $ref: paths/jaeger.api_v2.CollectorService_PostSpans.yaml /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 + $ref: paths/jaeger.api_v2.SamplingManager_GetSamplingStrategy.yaml /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 + $ref: paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml /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 + $ref: paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml /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 + $ref: paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml /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 + $ref: paths/v1_metrics.yaml /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 + $ref: paths/v1_traces.yaml /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 + $ref: paths/v1_logs.yaml components: securitySchemes: apiKeyAuth: @@ -382,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 d8ed23e0ce8..2a75bedf90a 100644 --- a/docs/spec/openapi/bundled.json +++ b/docs/spec/openapi/bundled.json @@ -565,111 +565,46 @@ "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" - ], - "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. \n", - "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. \n", - "required": [ - "metricset" - ], - "properties": { - "metricset": { - "$ref": "#/components/schemas/metricset" - } - } - }, - "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" - } - } - }, - "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.\n", - "required": [ - "transaction" - ], - "properties": { - "transaction": { - "$ref": "#/components/schemas/transaction" - } - } - }, - "TransactionEventv3": { - "type": "object", - "required": [ - "transaction" - ], - "properties": { - "transaction": { - "$ref": "#/components/schemas/transaction-2" + "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.", @@ -1963,6 +1898,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", @@ -2538,6 +2485,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", @@ -2839,6 +2798,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", @@ -3742,6 +3713,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", @@ -4873,6 +4856,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", @@ -5720,6 +5715,17 @@ } ] }, + "ErrorEventv3": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "$ref": "#/components/schemas/error-2" + } + } + }, "metadata-2": { "$id": "docs/spec/rumv3/metadata", "type": "object", @@ -5938,6 +5944,17 @@ "se" ] }, + "MetadataEventv3": { + "type": "object", + "required": [ + "metadata" + ], + "properties": { + "metadata": { + "$ref": "#/components/schemas/metadata-2" + } + } + }, "span-2": { "$id": "docs/spec/rumv3/span", "type": "object", @@ -6302,6 +6319,17 @@ "d" ] }, + "SpanEventv3": { + "type": "object", + "required": [ + "span" + ], + "properties": { + "span": { + "$ref": "#/components/schemas/span-2" + } + } + }, "transaction-2": { "$id": "docs/spec/rumv3/transaction", "type": "object", @@ -7300,43 +7328,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 ef635d8a6cd..3a00bfc4547 100644 --- a/docs/spec/openapi/bundled.yaml +++ b/docs/spec/openapi/bundled.yaml @@ -367,80 +367,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. @@ -1328,6 +1281,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 @@ -1744,6 +1706,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 @@ -1946,6 +1917,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 @@ -2582,6 +2562,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 @@ -3390,6 +3379,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 @@ -3974,6 +3972,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 @@ -4133,6 +4138,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 @@ -4397,6 +4409,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 @@ -5119,32 +5138,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..ab44382ba72 --- /dev/null +++ b/docs/spec/openapi/paths/intake_v2_events.yaml @@ -0,0 +1,51 @@ +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.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 From 14ee187c467b2fe560e05e3d3eb3e8f388c58c70 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 31 May 2024 11:48:37 -0700 Subject: [PATCH 5/5] Remove asyn parameter from intake_v2_events.yaml --- docs/spec/openapi/bundled.json | 10 ---------- docs/spec/openapi/bundled.yaml | 7 ------- docs/spec/openapi/paths/intake_v2_events.yaml | 14 -------------- 3 files changed, 31 deletions(-) diff --git a/docs/spec/openapi/bundled.json b/docs/spec/openapi/bundled.json index 2a75bedf90a..db24a1f41ab 100644 --- a/docs/spec/openapi/bundled.json +++ b/docs/spec/openapi/bundled.json @@ -231,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": { diff --git a/docs/spec/openapi/bundled.yaml b/docs/spec/openapi/bundled.yaml index 3a00bfc4547..80842a9740e 100644 --- a/docs/spec/openapi/bundled.yaml +++ b/docs/spec/openapi/bundled.yaml @@ -161,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: diff --git a/docs/spec/openapi/paths/intake_v2_events.yaml b/docs/spec/openapi/paths/intake_v2_events.yaml index ab44382ba72..e9da3077ea2 100644 --- a/docs/spec/openapi/paths/intake_v2_events.yaml +++ b/docs/spec/openapi/paths/intake_v2_events.yaml @@ -17,20 +17,6 @@ post: 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: