Document all the APIs (#11592) (#11610)

* docs: api work * clean up (cherry picked from commit 21461ac) Co-authored-by: Brandon Morelli <[email protected]>
elastic · Sep 8, 2023 · 549248e · 549248e
1 parent b823149
commit 549248e
Show file tree

Hide file tree

Showing 6 changed files with 90 additions and 14 deletions.
diff --git 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 <<api-key>> or a <<secret-token>> 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 <<api-key>> or <<secret-token>> 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
@@ -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 <<data-model,APM data model>> 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 <<apm-rum,RUM>> send an `HTTP POST` request to the APM Server `intake/v2/rum/events` endpoint instead:
+For <<apm-rum,RUM>> 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
@@ -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
@@ -0,0 +1,14 @@
+[[api-jaeger]]
+=== Jaeger event intake
+
+Elastic APM natively supports Jaeger, an open-source, distributed tracing system.
+<<jaeger-integration,Learn more>>.
+
+**Jaeger/gRPC paths**
+
+[options="header"]
+|====
+|Name |Endpoint
+|Jaeger span intake |`/jaeger.api_v2.CollectorService/PostSpans`
+|Sampling endpoint |`/jaeger.api_v2.SamplingManager/GetSamplingStrategy`
+|====
diff --git a/docs/api-otlp.asciidoc 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
+<<instrument-apps-otel,OpenTelemetry agent>> or
+<<connect-open-telemetry-collector,OpenTelemetry collector>>.
diff --git a/docs/api.asciidoc b/docs/api.asciidoc
@@ -3,10 +3,14 @@
 
 The APM Server exposes endpoints for:
 
-* <<api-events,Events intake>>
-* <<api-config,Agent configuration>>
-* <<api-info,Server information>>
+* <<api-info>>
+* <<api-events>>
+* <<api-config>>
+* <<api-otlp>>
+* <<api-jaeger>>
 
+include::./api-info.asciidoc[]
 include::./api-events.asciidoc[]
 include::./api-config.asciidoc[]
-include::./api-info.asciidoc[]
+include::./api-otlp.asciidoc[]
+include::./api-jaeger.asciidoc[]