diff --git a/solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md b/solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md new file mode 100644 index 0000000000..4b8e6493f4 --- /dev/null +++ b/solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md @@ -0,0 +1,21 @@ +To create an {{apm-agent}} key: + +1. In {{kib}}, find **Applications** in the main menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). +2. Select any **Applications** page. +3. Go to **Settings** > **Agent keys**. +4. Select **Create {{apm-agent}} key**. +5. Enter a name for your API key. +6. Assign at least one privilege: + - **Agent configuration** (`config_agent:read`): Required to use agent central configuration for remote configuration. + - **Ingest** (`event:write`): Required to ingest agent events. +7. Select **Create {{apm-agent}} key**. +8. Copy the API key now. The key is shown only once. + +:::{note} +API keys do not expire. +::: + +:::{image} /solutions/images/observability-apm-ui-api-key.png +:alt: {{apm-agent}} key creation +:screenshot: +::: \ No newline at end of file diff --git a/solutions/observability/apm/api-keys.md b/solutions/observability/apm/api-keys.md index e4f57fb656..a68a97edca 100644 --- a/solutions/observability/apm/api-keys.md +++ b/solutions/observability/apm/api-keys.md @@ -32,6 +32,10 @@ To secure the communication between APM Agents and either {{apm-server-or-mis}} 3. [Create an API key in {{kib}}](#apm-create-an-api-key) 4. [Set the API key in your APM agents](#apm-agent-api-key) +::::{note} +If you're using [{{edot}} (EDOT) SDKs](opentelemetry://reference/edot-sdks/index.md), refer to [Create {{apm-agent}} key for EDOT SDKs](/solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md) for EDOT-specific guidance on creating and using API keys. +:::: + ## Enable API keys [apm-enable-api-key] :::::::{tab-set} @@ -111,42 +115,12 @@ Assign the newly created `apm_agent_key_role` role to any user that wishes to cr The Applications UI has a built-in workflow that you can use to easily create and view {{apm-agent}} API keys. Only API keys created in the Applications UI will show up here. -:::::::{tab-set} - -::::::{tab-item} Fleet-managed or APM Server binary - -Using a superuser account, or a user with the role created in the previous step, In {{kib}}, find **Applications** in the main menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). Go to **Settings** → **Agent keys**. Enter a name for your API key and select at least one privilege. - -For example, to create an API key that can be used to ingest APM events and read agent central configuration, select `config_agent:read` and `event:write`. - -Click **Create APM Agent key** and copy the Base64 encoded API key. You will need this for the next step, and you will not be able to view it again. - -:::{image} /solutions/images/observability-apm-ui-api-key.png -:alt: Applications UI API key -:screenshot: +:::{include} _snippets/create-apm-agent-key-applications-ui.md ::: -:::::: - -::::::{tab-item} {{serverless-full}} -To create a new API key: - -1. In your Elastic Observability Serverless project, go to any Applications page. -1. Click **Settings**. -1. Select the **Agent keys** tab. -1. Click **Create APM agent key**. -1. Name the key and assign privileges to it. -1. Click **Create APM agent key**. -1. Copy the key now. You will not be able to see it again. API keys do not expire. +For example, to create an API key that can be used to ingest {{product.apm}} events and read agent central configuration, select `config_agent:read` and `event:write`. -To view all API keys for your project: - -1. Expand **Project settings**. -1. Select **Management**. -1. Select **API keys**. -:::::: - -::::::: +To view all API keys for your {{serverless-full}} project, expand **{{project-settings}}**, select **{{manage-app}}**, and then select **API keys**. ## Set the API key in your APM agents [apm-agent-api-key] diff --git a/solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md b/solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md new file mode 100644 index 0000000000..6b2dc02248 --- /dev/null +++ b/solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md @@ -0,0 +1,69 @@ +--- +navigation_title: Create APM agent key for EDOT SDKs +description: Learn how to create an APM agent key for Elastic Distribution of OpenTelemetry (EDOT) SDKs using Kibana. +applies_to: + stack: ga + serverless: ga +products: + - id: observability + - id: apm + - id: cloud-serverless +--- + +# Create {{apm-agent}} key for EDOT SDKs [create-apm-agent-key-for-edot-sdks] + +{{apm-agent}} keys are least-privilege API keys for ingesting {{product.apm}} data. Create these keys using the Applications UI in {{kib}}. + +::::{important} +{{apm-agent}} keys are sent as plain text, so they only provide security when used in combination with [TLS](/solutions/observability/apm/apm-agent-tls-communication.md). +:::: + +## Difference from {{stack-manage-app}} API keys + +There are two ways to create API keys in {{kib}}: + +* **{{stack-manage-app}} > API keys > Create API key**: Creates general-purpose API keys for {{es}} operations. For more information, refer to [{{es}} API keys](/deploy-manage/api-keys/elasticsearch-api-keys.md). +* **Applications > Settings > Agent keys > Create {{apm-agent}} key** (the method described on this page): Creates API keys specifically for ingesting {{product.apm}} data. All [{{edot}} (EDOT) SDKs](opentelemetry://reference/edot-sdks/index.md) should use this method. + +## Create an {{apm-agent}} key + +The Applications UI provides a built-in workflow to create {{apm-agent}} keys. These keys have the minimum required privileges for EDOT SDKs to send data to Elastic. + +:::{include} ../_snippets/create-apm-agent-key-applications-ui.md +::: + +For EDOT SDKs, the **Agent configuration** privilege enables [EDOT SDKs Central Configuration](opentelemetry://reference/central-configuration.md) for remote configuration. + +## Use the {{apm-agent}} key with EDOT SDKs + +After creating the {{apm-agent}} key, configure your EDOT SDK to use it. Configuration details vary by language and deployment: + +* **Android**: [`apiKey`](apm-agent-android://reference/edot-android/configuration.md) +* **.NET**: [`ApiKey`](apm-agent-dotnet://reference/config-reporter.md#config-api-key) +* **iOS**: [`withApiKey`](apm-agent-ios://reference/edot-ios/configuration.md#withapikey) +* **Java**: [`api_key`](elastic-otel-java://reference/edot-java/configuration.md) +* **Node.js**: [`apiKey`](elastic-otel-node://reference/edot-node/configuration.md) +* **PHP**: [`api_key`](elastic-otel-php://reference/edot-php/configuration.md) +* **Python**: [`api_key`](elastic-otel-python://reference/edot-python/configuration.md) + +## Required user privileges + +To create an {{apm-agent}} key, you must have the required privileges: + +:::::::{tab-set} + +::::::{tab-item} {{fleet}}-managed or {{apm-server}} binary + +You must have the `manage_own_api_key` cluster privilege and the {{product.apm}} application privileges you plan to assign to the key. Additionally, appropriate {{kib}} Space and Feature privileges are needed to access the Applications UI. + +For details on configuring the minimum required privileges, refer to [API keys for Elastic {{product.apm}}](/solutions/observability/apm/api-keys.md#apm-create-api-key-user). + +:::::: + +::::::{tab-item} {{serverless-full}} + +For {{observability}} {{serverless-short}} projects, the Editor role or higher is required to create and manage API keys. Refer to [Assign user roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles) for more information. + +:::::: + +::::::: \ No newline at end of file diff --git a/solutions/observability/get-started/quickstart-monitor-your-application-performance.md b/solutions/observability/get-started/quickstart-monitor-your-application-performance.md index a24932aed2..9b60129fa8 100644 --- a/solutions/observability/get-started/quickstart-monitor-your-application-performance.md +++ b/solutions/observability/get-started/quickstart-monitor-your-application-performance.md @@ -21,15 +21,15 @@ In this quickstart guide, you’ll learn how to instrument your application usin * An {{observability}} project. To learn more, refer to [Create an Observability project](/solutions/observability/get-started.md). * A user with the **Admin** role or higher—required to onboard system logs and metrics. To learn more, refer to [Assign user roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles). * An {{edot}} (EDOT) Collector or the contrib OpenTelemetry Collector running on the host. - +* An {{apm-agent}} key for authenticating your EDOT SDKs. To create one, refer to [Create {{apm-agent}} key for EDOT SDKs](/solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md). ::: :::{applies-item} stack: -* An {{es}} cluster for storing and searching your data, and {{kib}} for visualizing and managing your data. This quickstart is available for all Elastic deployment models. The quickest way to get started with this quickstart is using a trial project on [Elastic serverless](/solutions/observability/get-started.md). -* A user with the **Admin** role or higher—required to onboard system logs and metrics. To learn more, refer to [User roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md). +* An {{observability}} project. To learn more, refer to [Create an Observability project](/solutions/observability/get-started.md). +* A user with the **Admin** role or higher—required to onboard system logs and metrics. To learn more, refer to [Assign user roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles). * An {{edot}} (EDOT) Collector or the contrib OpenTelemetry Collector running on the host. - +* An {{apm-agent}} key for authenticating your EDOT SDKs. To create one, refer to [Create {{apm-agent}} key for EDOT SDKs](/solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md). ::: :::: diff --git a/solutions/toc.yml b/solutions/toc.yml index 179ed13956..a924c51eff 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -152,6 +152,7 @@ toc: children: - file: upstream-opentelemetry-collectors-language-sdks.md - file: collect-metrics.md + - file: create-apm-agent-key-for-edot-sdks.md - file: edot-sdks-central-configuration.md - file: limitations.md - file: attributes.md