From 287fa6fc9d250e8be4ccf82c4dfab7f110435e79 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Fri, 8 Sep 2023 08:18:37 +0000 Subject: [PATCH] Document all the APIs (#11592) (#11611) * docs: api work * clean up (cherry picked from commit 21461ac0988fd1e4763b63c45cdd04ea05f41065) Co-authored-by: Brandon Morelli Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> --- docs/api-config.asciidoc | 17 ++++++++++++----- docs/api-events.asciidoc | 22 ++++++++++++++++++---- docs/api-info.asciidoc | 2 +- docs/api-jaeger.asciidoc | 14 ++++++++++++++ docs/api-otlp.asciidoc | 37 +++++++++++++++++++++++++++++++++++++ docs/api.asciidoc | 12 ++++++++---- 6 files changed, 90 insertions(+), 14 deletions(-) create mode 100644 docs/api-jaeger.asciidoc create mode 100644 docs/api-otlp.asciidoc diff --git a/docs/api-config.asciidoc b/docs/api-config.asciidoc index 7ce60c0979a..ef78db2272d 100644 --- a/docs/api-config.asciidoc +++ b/docs/api-config.asciidoc @@ -1,15 +1,22 @@ [[api-config]] -=== Agent configuration API +=== Elastic APM agent configuration API -APM Server exposes an API endpoint that allows agents to query the server for configuration changes. +APM Server exposes API endpoints that allow Elastic APM agents to query the APM Server for configuration changes. More information on this feature is available in {kibana-ref}/agent-configuration.html[{apm-agent} configuration in {kib}]. [float] [[api-config-endpoint]] -=== Agent configuration endpoint +=== Agent configuration endpoints -The Agent configuration endpoint accepts both `HTTP GET` and `HTTP POST` requests. -If <> or a <> is configured, requests to this endpoint must be authenticated. +[options="header"] +|==== +|Name |Endpoint +|Agent configuration intake |`/config/v1/agents` +|RUM configuration intake |`/config/v1/rum/agents` +|==== + +The Agent configuration endpoints accepts both `HTTP GET` and `HTTP POST` requests. +If an <> or <> is configured, requests to this endpoint must be authenticated. [float] [[api-config-api-get]] diff --git a/docs/api-events.asciidoc b/docs/api-events.asciidoc index 2c9acd56a03..e83604972f5 100644 --- a/docs/api-events.asciidoc +++ b/docs/api-events.asciidoc @@ -1,5 +1,5 @@ [[api-events]] -=== Events intake API +=== Elastic APM events intake API NOTE: Most users do not need to interact directly with the events intake API. @@ -24,7 +24,21 @@ See the <> to learn more about the different types of [[api-events-endpoint]] [float] -=== Endpoint +=== Endpoints + +APM Server exposes the following endpoints for Elastic APM agent data intake: + +[options="header"] +|==== +|Name |Endpoint +|APM agent event intake |`/intake/v2/events` +|RUM event intake (v2) |`/intake/v2/rum/events` +|RUM event intake (v3) |`/intake/v3/rum/events` +|==== + +[[api-events-example]] +[float] +=== Request Send an `HTTP POST` request to the APM Server `intake/v2/events` endpoint: @@ -49,11 +63,11 @@ Furthermore, asynchronous processing requests will only be scheduled if the APM service the incoming request, requests that cannot be serviced will receive an internal error `503` "queue is full" error. -For <> send an `HTTP POST` request to the APM Server `intake/v2/rum/events` endpoint instead: +For <> send an `HTTP POST` request to the APM Server `intake/v3/rum/events` endpoint instead: [source,bash] ------------------------------------------------------------ -http(s)://{hostname}:{port}/intake/v2/rum/events +http(s)://{hostname}:{port}/intake/v3/rum/events ------------------------------------------------------------ [[api-events-response]] diff --git a/docs/api-info.asciidoc b/docs/api-info.asciidoc index 517b90fa039..3bd7544ed54 100644 --- a/docs/api-info.asciidoc +++ b/docs/api-info.asciidoc @@ -1,5 +1,5 @@ [[api-info]] -=== Server information API +=== APM Server information API The APM Server exposes an API endpoint to query general server information. This lightweight endpoint is useful as a server up/down health check. diff --git a/docs/api-jaeger.asciidoc b/docs/api-jaeger.asciidoc new file mode 100644 index 00000000000..af4a8add47c --- /dev/null +++ b/docs/api-jaeger.asciidoc @@ -0,0 +1,14 @@ +[[api-jaeger]] +=== Jaeger event intake + +Elastic APM natively supports Jaeger, an open-source, distributed tracing system. +<>. + +**Jaeger/gRPC paths** + +[options="header"] +|==== +|Name |Endpoint +|Jaeger span intake |`/jaeger.api_v2.CollectorService/PostSpans` +|Sampling endpoint |`/jaeger.api_v2.SamplingManager/GetSamplingStrategy` +|==== \ No newline at end of file diff --git a/docs/api-otlp.asciidoc b/docs/api-otlp.asciidoc new file mode 100644 index 00000000000..99f583c4669 --- /dev/null +++ b/docs/api-otlp.asciidoc @@ -0,0 +1,37 @@ +[[api-otlp]] +=== OpenTelemetry intake API + +APM Server supports receiving traces, metrics, and logs over the +https://opentelemetry.io/docs/specs/otlp/[OpenTelemetry Protocol (OTLP)]. +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) +* OTLP/gRPC + +[discrete] +=== OTLP/gRPC paths + +[options="header"] +|==== +|Name |Endpoint +|OTLP metrics intake |`/opentelemetry.proto.collector.metrics.v1.MetricsService/Export` +|OTLP trace intake |`/opentelemetry.proto.collector.trace.v1.TraceService/Export` +|OTLP logs intake |`/opentelemetry.proto.collector.logs.v1.LogsService/Export` +|==== + +[discrete] +==== OTLP/HTTP paths + +[options="header"] +|==== +|Name |Endpoint +|OTLP metrics intake |`/v1/metrics` +|OTLP trace intake |`/v1/traces` +|OTLP logs intake |`/v1/logs` +|==== + +TIP: See our OpenTelemetry documentation to learn how to send data to the APM Server from an +<> or +<>. diff --git a/docs/api.asciidoc b/docs/api.asciidoc index 8afaa83f25d..61e36d21a7a 100644 --- a/docs/api.asciidoc +++ b/docs/api.asciidoc @@ -3,10 +3,14 @@ The APM Server exposes endpoints for: -* <> -* <> -* <> +* <> +* <> +* <> +* <> +* <> +include::./api-info.asciidoc[] include::./api-events.asciidoc[] include::./api-config.asciidoc[] -include::./api-info.asciidoc[] +include::./api-otlp.asciidoc[] +include::./api-jaeger.asciidoc[]