elastic / elastic/apm-server

docs: Incorrect docs on standalone apm roles causing missing permissions on `traces-apm.sampled` data stream

Open
#18,401 0 comments 0 reactions 0 assignees View on GitHub
bug docs
Dominant language
Go
Stars
1.3k
Forks
543
Avg merge
1d 18h
Merged PRs (30d)
109

Description

**APM Server version** (`apm-server version`): confirmed on 8.19.2 but should affect many versions

**Description of the problem including expected versus actual behavior**:

expected: follow apm docs on setting up apm_writer and other roles, see no errors when using TBS
actual: follow apm docs on setting up apm_writer and other roles, see 403 permission error logs due to pubsub when using TBS

This docs bug need to be checked and fixed in both 8.x and 9.x. 9.x has a `apm_tail_based_sampling` role from PR https://github.com/elastic/docs-content/pull/1065 but appears to be incomplete.

**Steps to reproduce**:

Please include a *minimal* but *complete* recreation of the problem,
including server configuration, agent(s) used, etc. The easier you make it
for us to reproduce it, the more likely that somebody will take the time to
look at it.

1. follow [9.x docs](https://www.elastic.co/docs/solutions/observability/apm/grant-access-using-api-keys) and [8.19 docs](https://www.elastic.co/guide/en/observability/8.19/apm-feature-roles.html#apm-privileges-to-publish-events) to setup api key for standalone apm-server
2. enable tbs
3. observe for pubsub error logs from apm-server

**Provide logs (if relevant)**:

```
"action [indices:monitor/stats] is unauthorized for user [apm_server] with effective roles [apm_writer] on indices [traces-apm.sampled-test], this action is granted by the index privileges [monitor,cross_cluster_replication,manage,all]"
```

```
action [indices:admin/refresh] is unauthorized for user [apm_server] with effective roles [apm_writer] on indices [.ds-traces-apm.sampled-test-2025.08.25-001441,.ds-traces-apm.sampled-test-2025.08.24-001433,.ds-traces-apm.sampled-test-2025.08.24-001435,.ds-traces-apm.sampled-test-2025.08.24-001437,.ds-traces-apm.sampled-test-2025.08.24-001439], this action is granted by the index privileges [maintenance,manage,all]"
```

```
action [indices:data/read/search] is unauthorized for user [apm_server] with effective roles [apm_writer] on indices [.ds-traces-apm.sampled-test-2025.08.24-001437], this action is granted by the index privileges [read,all]"
```

Contributor guide

Open the contributing guide

Research direction

Start with the linked 9.x and 8.19 APM role documentation and compare the standalone apm_writer privileges with the reported traces-apm.sampled permission errors. Check the referenced 9.x apm_tail_based_sampling role as well. Update the affected role documentation for both 8.x and 9.x, then verify that enabling TBS no longer produces the listed 403 errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
elasticsearch
Domain
authorization, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.