Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.x] [APM][docs] Add troubleshooting for non-indexed fields (#54948) #57136

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions docs/apm/troubleshooting.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ your proposed changes in the https://github.com/elastic/kibana[Kibana repository

Also check out the https://discuss.elastic.co/c/apm[APM discussion forum].

[[no-apm-data-found]]
==== No APM data found

This section can help with any of the following:
Expand Down Expand Up @@ -69,3 +70,41 @@ or because something is happening to the request that the Agent doesn't understa
To resolve this, you'll need to head over to the relevant {apm-agents-ref}[Agent documentation].
Specifically, view the Agent's supported technologies page.
You can also use the Agent's public API to manually set a name for the transaction.

==== Fields are not searchable

In Elasticsearch, index patterns are used to define settings and mappings that determine how fields should be analyzed.
The recommended index template file for APM Server is installed when Kibana starts.
This template defines which fields are available in Kibana for features like the Kuery bar,
or for linking to other plugins like Logs, Uptime, and Discover.

As an example, some agents store cookie values in `http.request.cookies`.
Since `http.request` has disabled dynamic indexing, and `http.request.cookies` is not declared in a custom mapping,
the values in `http.request.cookies` are not indexed and thus not searchable.

*Ensure an index pattern exists*
As a first step, you should ensure the correct index pattern exists.
In Kibana, navigate to *Management > Kibana > Index Patterns*.
In the pattern list, you should see an apm index pattern; The default is `apm-*`.
If you don't, the index pattern doesn't exist. See <<no-apm-data-found>> for information on how to fix this problem.

Selecting the `apm-*` index pattern shows a listing of every field defined in the pattern.

*Ensure a field is searchable*
There are two things you can do to if you'd like to ensure a field is searchable:

1. Index your additional data as {apm-overview-ref}/metadata.html[labels] instead.
These are dynamic by default, which means they will be indexed and become searchable and aggregatable.

2. Use the {apm-server-ref}/configuration-template.html[`append_fields`] feature. As an example,
adding the following to `apm-server.yml` will enable dynamic indexing for `http.request.cookies`:

[source,yml]
----
setup.template.enabled: true
setup.template.overwrite: true
setup.template.append_fields:
- name: http.request.cookies
type: object
dynamic: true
----