Add documentation for creating APM agent keys for EDOT SDKs #4554

alexandra5000 · 2026-01-08T16:00:27Z

Summary

This PR adds a dedicated page for creating APM agent keys for EDOT SDKs, with a reusable snippet to reduce content duplication. This change addresses the need for EDOT-specific API key documentation.

Closes #4296

Generative AI disclosure

To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following:

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: Claude 4.5 Sonnet to help draft some sections, make the snippet work as it should, fix build errors, etc.

github-actions · 2026-01-08T16:01:36Z

Vale Linting Results

Summary: 3 suggestions found

💡 Suggestions (3)

File	Line	Rule	Message
solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md	16	Elastic.FutureTense	'won't be' might be in future tense. Write in the present tense to describe the state of the product as it is now.
solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md	37	Elastic.FutureTense	'won't be' might be in future tense. Write in the present tense to describe the state of the product as it is now.
solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md	65	Elastic.Versions	Use 'or later' instead of 'or higher' when referring to versions.

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

github-actions · 2026-01-08T16:04:44Z

🔍 Preview links for changed docs

alexandra5000 · 2026-01-08T16:06:35Z

Vale Linting Results

Summary: 3 suggestions found

💡 Suggestions (3)

To the future reviewer: I don't think these are good suggestions in the context of this change. LMK if you disagree!

…ent API keys; remove redundant information

theletterf

Good work! Some suggestions.

theletterf · 2026-01-09T14:53:42Z

solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md

+   - **Ingest** (`event:write`): Required to ingest agent events.
+   - **Agent configuration** (`config_agent:read`): Required to use agent central configuration for remote configuration.
+7. Select **Create {{apm-agent}} key**.
+8. Copy the API key now. You won't be able to view it again.


One way of rewriting this in present tense:

"The key is shown only once."

theletterf · 2026-01-09T14:54:08Z

solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md

+   - **Ingest** (`event:write`): Required to ingest agent events.
+   - **Agent configuration** (`config_agent:read`): Required to use agent central configuration for remote configuration.
+6. Select **Create {{apm-agent}} key**.
+7. Copy the API key now. You won't be able to view it again. API keys do not expire.


Same here. I would also move the "do not expire" observation to a note outside of this step to avoid mixing concepts.

theletterf · 2026-01-09T14:54:49Z

solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md

+
+::::::{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.


In this case, "or higher" makes sense :)

theletterf · 2026-01-09T14:56:05Z

solutions/images/observability-apm-ui-api-key-serverless.png

Do we need to blur or obscure details here? The user number for example?

mdbirnstiehl

Overall looks good! I left a few comments, let me know what you think.

mdbirnstiehl · 2026-01-09T15:48:58Z

solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md

+   - **Ingest** (`event:write`): Required to ingest agent events.
+   - **Agent configuration** (`config_agent:read`): Required to use agent central configuration for remote configuration.


I see these two options in the opposite order (config_agent:read first then event:write). Unless we are reordering here for some other reason, it might be good to align with the UI.

mdbirnstiehl · 2026-01-09T15:51:07Z

solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md

+
+To create an {{apm-agent}} key:
+
+1. In your {{obs-serverless}} project, go to any **Applications** page.


This step is the same in serverless and stack, but we're using different language. Do we want to use the same language in these?

mdbirnstiehl · 2026-01-09T15:53:32Z

solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md

+To create an {{apm-agent}} key:
+
+1. In your {{obs-serverless}} project, go to any **Applications** page.
+2. Select **Settings** > **Agent keys**.


Suggested change

2. Select **Settings** > **Agent keys**.

2. Go to **Settings** > **Agent keys**.

Aligning the language between serverless/stack.

mdbirnstiehl · 2026-01-09T15:56:20Z

solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md

+
+::::::
+
+::::::{tab-item} {{serverless-full}}


It seems the only difference between the serverless and stack is whether you're in a serverless project or stack deployment. Do we need tabs here? (I say this as the person that probably set up these tabs during migration 😄)

++ good callout. We can really simplify by removing the tabs

mdbirnstiehl · 2026-01-09T16:48:58Z

solutions/observability/apm/_snippets/create-apm-agent-key-applications-ui.md

+   - **Ingest** (`event:write`): Required to ingest agent events.
+   - **Agent configuration** (`config_agent:read`): Required to use agent central configuration for remote configuration.


same comment as above.

bmorelli25 · 2026-01-09T22:16:27Z

solutions/observability/apm/opentelemetry/create-apm-agent-key-for-edot-sdks.md

+
+::::::{tab-item} {{fleet}}-managed or {{apm-server}} binary
+
+You must have the `manage_own_api_key` cluster privilege and the {{product.apm}} application privileges they intend to assign. Additionally, appropriate {{kib}} Space and Feature privileges are needed to access the Applications UI.


I think the "they" is too ambiguous here. Something like this might be better:

Suggested change

You must have the `manage_own_api_key` cluster privilege and the {{product.apm}} application privileges they intend to assign. Additionally, appropriate {{kib}} Space and Feature privileges are needed to access the Applications UI.

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.

alexandra5000 added 2 commits December 19, 2025 20:26

Add documentation for creating APM agent keys for EDOT SDKs

8a99622

Add APM agent key documentation for EDOT SDKs

a9dc964

github-actions bot had a problem deploying to docs-preview January 8, 2026 16:01 Failure

Merge branch 'main' into api-agent-keys

e653a9f

github-actions bot deployed to docs-preview January 8, 2026 16:03 View deployment

Merge branch 'main' into api-agent-keys

18968c2

github-actions bot deployed to docs-preview January 9, 2026 11:08 View deployment

Add a section distinguishing between APM agent keys and Stack Managem…

2633934

…ent API keys; remove redundant information

github-actions bot deployed to docs-preview January 9, 2026 11:54 View deployment

alexandra5000 marked this pull request as ready for review January 9, 2026 11:56

alexandra5000 requested review from a team as code owners January 9, 2026 11:56

theletterf requested changes Jan 9, 2026

View reviewed changes

mdbirnstiehl reviewed Jan 9, 2026

View reviewed changes

bmorelli25 reviewed Jan 9, 2026

View reviewed changes


		::::::{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.

		- Ingest (`event:write`): Required to ingest agent events.
		- Agent configuration (`config_agent:read`): Required to use agent central configuration for remote configuration.


		To create an {{apm-agent}} key:

		1. In your {{obs-serverless}} project, go to any Applications page.

	2. Select Settings > Agent keys.
	2. Go to Settings > Agent keys.


		::::::{tab-item} {{fleet}}-managed or {{apm-server}} binary

		You must have the `manage_own_api_key` cluster privilege and the {{product.apm}} application privileges they intend to assign. Additionally, appropriate {{kib}} Space and Feature privileges are needed to access the Applications UI.

Add documentation for creating APM agent keys for EDOT SDKs #4554

Are you sure you want to change the base?

Add documentation for creating APM agent keys for EDOT SDKs #4554

Conversation

alexandra5000 commented Jan 8, 2026

Summary

Generative AI disclosure

Uh oh!

github-actions bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

github-actions bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

alexandra5000 commented Jan 8, 2026

Vale Linting Results

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdbirnstiehl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Jan 8, 2026 •

edited

Loading

github-actions bot commented Jan 8, 2026 •

edited

Loading