From bd8f190463c70bb961e781d5d578429e18adbb39 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 25 Jul 2024 10:18:51 -0500 Subject: [PATCH 1/2] proof of concept --- docs/en/observability/apm.asciidoc | 4 +- docs/en/observability/apm/api-keys.asciidoc | 16 ++++-- .../apm/collect-application-data.asciidoc | 55 +++++++++++++++++++ .../apm/elastic-apm-agents.asciidoc | 4 ++ ...-distributions-for-open-telemetry.asciidoc | 4 ++ .../apm/getting-started-apm-server.asciidoc | 40 ++++++-------- .../observability/apm/open-telemetry.asciidoc | 2 + .../observability/apm/secret-token.asciidoc | 10 +++- .../apm/secure-agent-communication.asciidoc | 13 ++--- .../observability/apm/secure-comms.asciidoc | 2 +- docs/en/observability/apm/tls-comms.asciidoc | 18 ++++-- 11 files changed, 123 insertions(+), 45 deletions(-) create mode 100644 docs/en/observability/apm/collect-application-data.asciidoc create mode 100644 docs/en/observability/apm/elastic-apm-agents.asciidoc create mode 100644 docs/en/observability/apm/elastic-distributions-for-open-telemetry.asciidoc diff --git a/docs/en/observability/apm.asciidoc b/docs/en/observability/apm.asciidoc index 9b8d686183..7c3361bee9 100644 --- a/docs/en/observability/apm.asciidoc +++ b/docs/en/observability/apm.asciidoc @@ -48,14 +48,14 @@ Want to host everything yourself instead? See <> include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm-server.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data.asciidoc[] + include::{observability-docs-root}/docs/en/observability/apm/data-model.asciidoc[] include::{observability-docs-root}/docs/en/observability/apm/features.asciidoc[] include::{observability-docs-root}/docs/en/observability/apm/how-to.asciidoc[] -include::{observability-docs-root}/docs/en/observability/apm/open-telemetry.asciidoc[] - include::{observability-docs-root}/docs/en/observability/apm/manage-storage.asciidoc[] include::{observability-docs-root}/docs/en/observability/apm/configure/index.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/api-keys.asciidoc b/docs/en/observability/apm/api-keys.asciidoc index 03e63933bb..5ed9908a5c 100644 --- a/docs/en/observability/apm/api-keys.asciidoc +++ b/docs/en/observability/apm/api-keys.asciidoc @@ -5,7 +5,7 @@ IMPORTANT: API keys are sent as plain-text, so they only provide security when used in combination with <>. When enabled, API keys are used to authorize requests to the APM Server. -API keys are not applicable for APM agents running on clients, like the RUM agent, +API keys are not applicable for _{generic_term_for_agent_distro}_ s running on clients, like the RUM agent, as there is no way to prevent them from being publicly exposed. You can assign one or more unique privileges to each API key: @@ -14,13 +14,13 @@ You can assign one or more unique privileges to each API key: {kibana-ref}/agent-configuration.html[Agent configuration remotely]. * *Ingest* (`event:write`): Required for ingesting agent events. -To secure the communication between APM Agents and the APM Server with API keys, +To secure the communication between _{generic_term_for_agent_distro}_ and the APM Server with API keys, make sure <> is enabled, then complete these steps: . <> . <> . <> -. <> +. <> [[apm-enable-api-key]] [float] @@ -93,9 +93,9 @@ image::images/apm-ui-api-key.png[{apm-app} API key] [[apm-agent-api-key]] [float] -=== Set the API key in your APM agents +=== Set the API key in your _{generic_term_for_agent_distro}_ -You can now apply your newly created API keys in the configuration of each of your APM agents. +You can now apply your newly created API keys in the configuration of each of your _{generic_term_for_agent_distro}_. See the relevant agent documentation for additional information: // Not relevant for RUM @@ -109,6 +109,10 @@ See the relevant agent documentation for additional information: * *Python agent*: {apm-py-ref}/configuration.html#config-api-key[`api_key`] * *Ruby agent*: {apm-ruby-ref}/configuration.html#config-api-key[`api_key`] +* Java distro +* .NET distro +* Node distro + [[apm-configure-api-key-alternative]] [float] === Alternate API key creation methods @@ -252,7 +256,7 @@ The response will look similar to this: } ---- -The `credential` string, which is what agents use to communicate with APM Server, +The `credential` string, which is what _{generic_term_for_agent_distro}_ use to communicate with APM Server, is a base64 encoded representation of the API key's `id:api_key`. It can be created like this: diff --git a/docs/en/observability/apm/collect-application-data.asciidoc b/docs/en/observability/apm/collect-application-data.asciidoc new file mode 100644 index 0000000000..4135f26f6d --- /dev/null +++ b/docs/en/observability/apm/collect-application-data.asciidoc @@ -0,0 +1,55 @@ +[[apm-collect-application-data]] +== Collect application data + +:generic_term_for_agent_distro: + +There are several ways you can collect application data to send to Elastic. +Which option is best for your use case depends on several factors including: +, , and . + +//// +Compare/contrast methods for collection application data +//// +[discrete] +=== Elastic Distributions for OpenTelemetry + +// What is it + + +// Why use it + + +// Where to learn more +Read more about how to use Elastic APM agents in <>. + +[discrete] +=== Elastic APM agents + +// What is it + + +// Why use it + + +// Where to learn more +Read more about how to use Elastic APM agents in <>. + +[discrete] +=== Elastic OpenTelemetry integration + +// What is it + + +// Why use it + + +// Where to learn more +Read more about how to use Elastic APM agents in <>. + +include::secure-agent-communication.asciidoc[leveloffset=+1] + +include::elastic-distributions-for-open-telemetry.asciidoc[leveloffset=+1] + +include::elastic-apm-agents.asciidoc[leveloffset=+1] + +include::open-telemetry.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/elastic-apm-agents.asciidoc b/docs/en/observability/apm/elastic-apm-agents.asciidoc new file mode 100644 index 0000000000..cf17b43df4 --- /dev/null +++ b/docs/en/observability/apm/elastic-apm-agents.asciidoc @@ -0,0 +1,4 @@ +[[apm-agents]] +== Elastic APM agents + + diff --git a/docs/en/observability/apm/elastic-distributions-for-open-telemetry.asciidoc b/docs/en/observability/apm/elastic-distributions-for-open-telemetry.asciidoc new file mode 100644 index 0000000000..26fe8122ca --- /dev/null +++ b/docs/en/observability/apm/elastic-distributions-for-open-telemetry.asciidoc @@ -0,0 +1,4 @@ +[[apm-elastic-distributions-for-open-telemetry]] +== Elastic Distributions for OpenTelemetry + + diff --git a/docs/en/observability/apm/getting-started-apm-server.asciidoc b/docs/en/observability/apm/getting-started-apm-server.asciidoc index 60051fdad8..6ae3bac9b1 100644 --- a/docs/en/observability/apm/getting-started-apm-server.asciidoc +++ b/docs/en/observability/apm/getting-started-apm-server.asciidoc @@ -15,7 +15,7 @@ See <> to get started in minut IMPORTANT: Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage APM index templates, {ilm-init} policies, and ingest pipelines. APM Server will only send data to {es} _after_ the APM integration has been installed. -The APM Server receives performance data from your APM agents, +The APM Server receives performance data from your _{generic_term_for_agent_distro}_, validates and processes it, and then transforms the data into {es} documents. If you're on this page, then you've chosen to self-manage the Elastic Stack, and you now must decide how to run and configure the APM Server. @@ -51,7 +51,7 @@ image::./images/bin-ov.png[APM Server binary overview] **Required components**: -- APM agents +- APM agents or Elastic Distributions for OpenTelemetry - APM Server - {stack} @@ -82,7 +82,7 @@ image::./images/fm-ov.png[APM Server fleet overview] **Required components**: -- APM agents +- APM agents or Elastic Distributions for OpenTelemetry - APM Server - {agent} - Fleet Server @@ -451,20 +451,10 @@ See the <> for a full directory la ==== Step 4: Next steps // Use a tagged region to pull APM Agent information from the APM Overview -If you haven't already, you can now install APM Agents in your services! - -* {apm-android-ref}/intro.html[Android agent] -* {apm-go-ref-v}/introduction.html[Go agent] -* {apm-ios-ref-v}/intro.html[iOS agent] -* {apm-java-ref-v}/intro.html[Java agent] -* {apm-dotnet-ref-v}/intro.html[.NET agent] -* {apm-node-ref-v}/intro.html[Node.js agent] -* {apm-php-ref-v}/intro.html[PHP agent] -* {apm-py-ref-v}/getting-started.html[Python agent] -* {apm-ruby-ref-v}/introduction.html[Ruby agent] -* {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent] - -Once you have at least one {apm-agent} sending data to APM Server, +If you haven't already, you can now install _{generic_term_for_agent_distro}_ in your services! +To choose the right option for your use case, refer to <>. + +Once you have at least one _{generic_term_for_agent_distro}_ sending data to APM Server, you can start visualizing your data in the {kibana-ref}/xpack-apm.html[{apm-app}]. If you're migrating from Jaeger, see <>. @@ -510,13 +500,15 @@ include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm -- **** -==== Step 3: Install APM agents +==== Step 3: Install _{generic_term_for_agent_distro}_ + +_{generic_term_for_agent_distro}_ are written in the same language as your service. +To choose the right option for your use case, refer to <>. -APM agents are written in the same language as your service. -To monitor a new service, you must install the agent and configure it with a service name, +To monitor a new service, you must install the _{generic_term_for_agent_distro}_ and configure it with a service name, APM Server host, and Secret token. -* **Service name**: The APM integration maps an instrumented service's name–defined in each {apm-agent}'s configuration– +* **Service name**: The APM integration maps an instrumented service's name–defined in each _{generic_term_for_agent_distro}_ 's configuration– to the index that its data is stored in {es}. Service names are case-insensitive and must be unique. For example, you cannot have a service named `Foo` and another named `foo`. @@ -525,11 +517,13 @@ Special characters will be removed from service names and replaced with undersco * **APM Server URL**: The host and port that APM Server listens for events on. This should match the host and port defined when setting up the APM integration. -* **Secret token**: Authentication method for {apm-agent} and APM Server communication. +* **Secret token**: Authentication method for _{generic_term_for_agent_distro}_ and APM Server communication. This should match the secret token defined when setting up the APM integration. TIP: You can edit your APM integration settings if you need to change the APM Server URL -or secret token to match your APM agents. +or secret token to match your _{generic_term_for_agent_distro}_. + + include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc[] diff --git a/docs/en/observability/apm/open-telemetry.asciidoc b/docs/en/observability/apm/open-telemetry.asciidoc index b1eda01588..9df41ec403 100644 --- a/docs/en/observability/apm/open-telemetry.asciidoc +++ b/docs/en/observability/apm/open-telemetry.asciidoc @@ -1,6 +1,8 @@ [[apm-open-telemetry]] == OpenTelemetry integration + + https://opentelemetry.io/docs/concepts/what-is-opentelemetry/[OpenTelemetry] is a set of APIs, SDKs, tooling, and integrations that enable the capture and management of telemetry data from your services and applications. For more information about the OpenTelemetry project, see the https://github.com/open-telemetry/opentelemetry-specification/blob/master/README.md[spec]. diff --git a/docs/en/observability/apm/secret-token.asciidoc b/docs/en/observability/apm/secret-token.asciidoc index 1ac8993a1e..1f6172e505 100644 --- a/docs/en/observability/apm/secret-token.asciidoc +++ b/docs/en/observability/apm/secret-token.asciidoc @@ -42,6 +42,10 @@ Each Elastic {apm-agent} has a configuration option to set the value of the secr * *Python agent*: {apm-py-ref}/configuration.html#config-secret-token[`secret_token`] * *Ruby agent*: {apm-ruby-ref}/configuration.html#config-secret-token[`secret_token`] +* Java distro +* .NET distro +* Node distro + In addition to setting the secret token, ensure the configured server URL uses `HTTPS` instead of `HTTP`: * *Go agent*: {apm-go-ref}/configuration.html#config-server-url[`ELASTIC_APM_SERVER_URL`] @@ -50,4 +54,8 @@ In addition to setting the secret token, ensure the configured server URL uses ` * *Node.js agent*: {apm-node-ref}/configuration.html#server-url[`serverUrl`] * *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-server-url[`server_url`] * *Python agent*: {apm-py-ref}/[`server_url`] -* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-server-url[`server_url`] \ No newline at end of file +* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-server-url[`server_url`] + +* Java distro +* .NET distro +* Node distro diff --git a/docs/en/observability/apm/secure-agent-communication.asciidoc b/docs/en/observability/apm/secure-agent-communication.asciidoc index 2e34ab600b..e1026e0ae2 100644 --- a/docs/en/observability/apm/secure-agent-communication.asciidoc +++ b/docs/en/observability/apm/secure-agent-communication.asciidoc @@ -1,22 +1,21 @@ [[apm-secure-agent-communication]] -== Secure communication with APM agents +== Secure communication with _{generic_term_for_agent_distro}_ ++++ -With APM agents +Secure communication ++++ -Communication between APM agents and {agent} can be both encrypted and authenticated. +Communication between _{generic_term_for_agent_distro}_ and {agent} can be both encrypted and authenticated. It is strongly recommended to use both TLS encryption and authentication as secrets are sent as plain text. * <> * <> * <> -As soon as an authenticated communication is enabled, -requests without a valid token or API key will be denied. -If both API keys and a secret token are enabled, APM agents can choose whichever mechanism they support. +As soon as an authenticated communication is enabled, requests without a valid token or API key will be denied. +If both API keys and a secret token are enabled, _{generic_term_for_agent_distro}_ can choose whichever mechanism they support. -In some use-cases, like when an {apm-agent} is running on the client side, +In some use cases, like when an _{generic_term_for_agent_distro}_ is running on the client side, authentication is not possible. See <> for more information. include::./tls-comms.asciidoc[] diff --git a/docs/en/observability/apm/secure-comms.asciidoc b/docs/en/observability/apm/secure-comms.asciidoc index 65b03d9543..5121da56b3 100644 --- a/docs/en/observability/apm/secure-comms.asciidoc +++ b/docs/en/observability/apm/secure-comms.asciidoc @@ -13,7 +13,7 @@ process and connecting securely to APM agents and the {stack}. * <> :leveloffset: +1 -include::secure-agent-communication.asciidoc[] +// include::secure-agent-communication.asciidoc[] // APM privileges include::{observability-docs-root}/docs/en/observability/apm/feature-roles.asciidoc[] diff --git a/docs/en/observability/apm/tls-comms.asciidoc b/docs/en/observability/apm/tls-comms.asciidoc index fbcbd16e51..5b5fc84932 100644 --- a/docs/en/observability/apm/tls-comms.asciidoc +++ b/docs/en/observability/apm/tls-comms.asciidoc @@ -1,8 +1,8 @@ [[apm-agent-tls]] -=== {apm-agent} TLS communication +=== TLS communication TLS is disabled by default. -When TLS is enabled for APM Server inbound communication, agents will verify the identity +When TLS is enabled for APM Server inbound communication, _{generic_term_for_agent_distro}_ will verify the identity of the APM Server by authenticating its certificate. When TLS is enabled, a certificate and corresponding private key are required. @@ -36,10 +36,10 @@ include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/tls-wid [float] [[apm-agent-self-sign-3]] -==== Step 3: Configure APM agents +==== Step 3: Configure _{generic_term_for_agent_distro}_ When the APM server uses a certificate that is not chained to a publicly-trusted certificate -(e.g. self-signed), additional configuration is required in the {apm-agent}: +(e.g. self-signed), additional configuration is required in the _{generic_term_for_agent_distro}_: * *Go agent*: certificate pinning through {apm-go-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`] * *Python agent*: certificate pinning through {apm-py-ref}/configuration.html#config-server-cert[`server_cert`] @@ -49,6 +49,10 @@ When the APM server uses a certificate that is not chained to a publicly-trusted * *Java agent*: adding the certificate to the JVM `trustStore`. See {apm-java-ref}/ssl-configuration.html#ssl-server-authentication[APM Server authentication] for more details. +* Java distro +* .NET distro +* Node distro + We do not recommend disabling {apm-agent} verification of the server's certificate, but it is possible: * *Go agent*: {apm-go-ref}/configuration.html#config-verify-server-cert[`ELASTIC_APM_VERIFY_SERVER_CERT`] @@ -59,9 +63,13 @@ We do not recommend disabling {apm-agent} verification of the server's certifica * *Ruby agent*: {apm-ruby-ref}/configuration.html#config-verify-server-cert[`verify_server_cert`] * *Node.js agent*: {apm-node-ref}/configuration.html#validate-server-cert[`verifyServerCert`] +* Java distro +* .NET distro +* Node distro + [float] [[apm-agent-client-cert]] === Client certificate authentication -APM Server does not require agents to provide a certificate for authentication, +APM Server does not require _{generic_term_for_agent_distro}_ s to provide a certificate for authentication, and there is no dedicated support for SSL/TLS client certificate authentication in Elastic’s backend agents. \ No newline at end of file From 4acdd815162af637babaae70b4ff9447343a227f Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 25 Jul 2024 11:42:29 -0500 Subject: [PATCH 2/2] fix build? --- docs/en/observability/apm/getting-started-apm-server.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/observability/apm/getting-started-apm-server.asciidoc b/docs/en/observability/apm/getting-started-apm-server.asciidoc index 6ae3bac9b1..6d12f7f1dc 100644 --- a/docs/en/observability/apm/getting-started-apm-server.asciidoc +++ b/docs/en/observability/apm/getting-started-apm-server.asciidoc @@ -500,7 +500,8 @@ include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm -- **** -==== Step 3: Install _{generic_term_for_agent_distro}_ +// Not just APM agents tho... +==== Step 3: Install APM agents _{generic_term_for_agent_distro}_ are written in the same language as your service. To choose the right option for your use case, refer to <>.