117 lines
5.4 KiB
Plaintext
117 lines
5.4 KiB
Plaintext
[[troubleshooting]]
|
|
== Troubleshoot common problems
|
|
|
|
++++
|
|
<titleabbrev>Troubleshooting</titleabbrev>
|
|
++++
|
|
|
|
If you have something to add to this section, please consider creating a pull request with
|
|
your proposed changes at https://github.com/elastic/kibana.
|
|
|
|
Also, check out the https://discuss.elastic.co/c/apm[APM discussion forum].
|
|
|
|
[float]
|
|
[[no-apm-data-found]]
|
|
=== No APM data found
|
|
|
|
This section can help with any of the following:
|
|
|
|
* Data isn't displaying in the APM app
|
|
* You see a message like "No Services Found",
|
|
* You see errors like "Fielddata is disabled on text fields by default..."
|
|
|
|
There are a number of factors that could be at play here.
|
|
One important thing to double-check first is your index template.
|
|
|
|
*Index template*
|
|
An APM index template must exist for the APM app to work correctly.
|
|
By default, this index template is created by APM Server on startup.
|
|
However, this only happens if `setup.template.enabled` is `true` in `apm-server.yml`.
|
|
You can create the index template manually by running `apm-server setup`.
|
|
Take note that index templates *cannot* be applied retroactively -- they are only applied at index creation time.
|
|
More information is available in {apm-server-ref}/apm-server-configuration.html[Set up and configure].
|
|
|
|
You can check for the existence of an APM index template using the
|
|
{ref}/indices-get-template.html[Get index template API].
|
|
If you're using the default index naming pattern, that request would be:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_template/apm-{version}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
*Using Logstash, Kafka, etc.*
|
|
If you're not outputting data directly from APM Server to Elasticsearch (perhaps you're using Logstash or Kafka),
|
|
then the index template will not be set up automatically. Instead, you'll need to
|
|
{apm-server-ref}/_manually_loading_template_configuration.html[load the template manually].
|
|
|
|
*Using a custom index names*
|
|
This problem can also occur if you've customized the index name that you write APM data to.
|
|
The default index name that APM writes events to can be found
|
|
{apm-server-ref}/elasticsearch-output.html#index-option-es[here].
|
|
If you change the default, you must also configure the `setup.template.name` and `setup.template.pattern` options.
|
|
See {apm-server-ref}/configuration-template.html[Load the Elasticsearch index template].
|
|
If the Elasticsearch index template has already been successfully loaded to the index,
|
|
you can customize the indices that the APM app uses to display data.
|
|
Navigate to *APM* > *Settings* > *Indices*, and change all `apm_oss.*Pattern` values to
|
|
include the new index pattern. For example: `customIndexName-*`.
|
|
|
|
[float]
|
|
=== Unknown route
|
|
|
|
The {apm-app-ref}/transactions.html[transaction overview] will only display helpful information
|
|
when the transactions in your services are named correctly.
|
|
If you're seeing "GET unknown route" or "unknown route" in the APM app,
|
|
it could be a sign that something isn't working as it should.
|
|
|
|
Elastic APM Agents come with built-in support for popular frameworks out-of-the-box.
|
|
This means, among other things, that the Agent will try to automatically name HTTP requests.
|
|
As an example, the Node.js Agent uses the route that handled the request, while the Java Agent uses the Servlet name.
|
|
|
|
"Unknown route" indicates that the Agent can't determine what to name the request,
|
|
perhaps because the technology you're using isn't supported, the Agent has been installed incorrectly,
|
|
or because something is happening to the request that the Agent doesn't understand.
|
|
|
|
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.
|
|
|
|
[float]
|
|
=== Fields are not searchable
|
|
|
|
In Elasticsearch, index templates are used to define settings and mappings that determine how fields should be analyzed.
|
|
The recommended index template file for APM Server is installed by the APM Server packages.
|
|
This template, by default, enables and disables indexing on certain fields.
|
|
|
|
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-v}/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
|
|
----
|