Skip to content
Merged
Show file tree
Hide file tree
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
18 changes: 9 additions & 9 deletions docs/reference/agent-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ Each filter function will be called just before data is being sent to the APM Se

Each filter function will be called in the order they were added, and will receive a `payload` object as the only argument, containing the data about to be sent to the APM Server.

The format of the payload depends on the event type being sent. For details about the different formats, see the [events intake API docs](docs-content://solutions/observability/apps/elastic-apm-events-intake-api.md).
The format of the payload depends on the event type being sent. For details about the different formats, see the [events intake API docs](docs-content://solutions/observability/apm/elastic-apm-events-intake-api.md).

The filter function is synchronous and should return the manipulated payload object. If a filter function doesn’t return any value or returns a falsy value, the remaining filter functions will not be called and the payload **will not** be sent to the APM Server.

Expand Down Expand Up @@ -134,7 +134,7 @@ Similar to [`apm.addFilter()`](#apm-add-filter), but the `fn` will only be calle

Added in: v3.14.0

Use `addMetadataFilter(fn)` to supply a filter function for the [metadata object](docs-content://solutions/observability/apps/elastic-apm-events-intake-api.md#apm-api-events-schema-definition) sent to the APM Server. This will allow you to manipulate the data being sent, for instance to remove possibly sensitive information.
Use `addMetadataFilter(fn)` to supply a filter function for the [metadata object](docs-content://solutions/observability/apm/elastic-apm-events-intake-api.md#apm-api-events-schema-definition) sent to the APM Server. This will allow you to manipulate the data being sent, for instance to remove possibly sensitive information.

Each filter function will be called in the order they were added, and will receive a `metadata` object as the only argument. The filter function is synchronous and must return the manipulated object. Example usage:

Expand All @@ -147,7 +147,7 @@ apm.addMetadataFilter(function dropArgv(metadata) {
})
```

Warning: It is the responsibility of the author to ensure the returned object conforms to the [metadata schema](docs-content://solutions/observability/apps/elastic-apm-events-intake-api.md#apm-api-events-schema-definition) otherwise all APM data injest will fail. A metadata filter that breaks the metadata will result in error logging from the agent, something like:
Warning: It is the responsibility of the author to ensure the returned object conforms to the [metadata schema](docs-content://solutions/observability/apm/elastic-apm-events-intake-api.md#apm-api-events-schema-definition) otherwise all APM data injest will fail. A metadata filter that breaks the metadata will result in error logging from the agent, something like:

```text
ERROR (elastic-apm-node): APM Server transport error (400): Unexpected APM Server response
Expand Down Expand Up @@ -196,7 +196,7 @@ It’s possible to call this function multiple times within the scope of the sam
If an error is captured, the context from the active transaction is used as context for the captured error, and any custom context given as the 2nd argument to [`apm.captureError`](#apm-capture-error) takes precedence and is shallow merged on top.

::::{tip}
Before using custom context, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available.
Before using custom context, ensure you understand the different types of [metadata](docs-content://solutions/observability/apm/metadata.md) that are available.
::::


Expand All @@ -216,7 +216,7 @@ apm.setLabel('productId', 42, false);
Set a label on the current transaction. You can set multiple labels on the same transaction. If an error happens during the current transaction, it will also get tagged with the same label.

::::{tip}
Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via [`apm.setCustomContext()`](#apm-set-custom-context)). Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available.
Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via [`apm.setCustomContext()`](#apm-set-custom-context)). Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apm/metadata.md) that are available.
::::


Expand Down Expand Up @@ -244,7 +244,7 @@ apm.addLabels({productId: 42, productName: 'butter'}, false);
Add several labels on the current transaction. You can add labels multiple times. If an error happens during the current transaction, it will also get tagged with the same labels.

::::{tip}
Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via [`apm.setCustomContext()`](#apm-set-custom-context)). Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available.
Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via [`apm.setCustomContext()`](#apm-set-custom-context)). Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apm/metadata.md) that are available.
::::


Expand All @@ -264,7 +264,7 @@ Added in: v3.47.0
Extends the [`globalLabels`](/reference/configuration.md#global-labels) configuration. It allows setting labels that are applied to all transactions. A potential use case is to specify a label with the state of your application: `'initializing' | 'available' | 'unhealthy'`.

::::{tip}
Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via [`apm.setCustomContext()`](#apm-set-custom-context)). Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available.
Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via [`apm.setCustomContext()`](#apm-set-custom-context)). Before using custom labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apm/metadata.md) that are available.
::::


Expand Down Expand Up @@ -328,7 +328,7 @@ This makes it possible to better group error messages that contain variable data

### Metadata [metadata]

To ease debugging it’s possible to send some extra data with each error you send to the APM Server. The APM Server intake API supports a lot of different metadata fields, most of which are automatically managed by the Elastic APM Node.js Agent. But if you wish you can supply some extra details using `user` or `custom`. For more details on the properties accepted by the events intake API see the [events intake API docs](docs-content://solutions/observability/apps/elastic-apm-events-intake-api.md).
To ease debugging it’s possible to send some extra data with each error you send to the APM Server. The APM Server intake API supports a lot of different metadata fields, most of which are automatically managed by the Elastic APM Node.js Agent. But if you wish you can supply some extra details using `user` or `custom`. For more details on the properties accepted by the events intake API see the [events intake API docs](docs-content://solutions/observability/apm/elastic-apm-events-intake-api.md).

To supply any of these extra fields, use the optional options argument when calling `apm.captureError()`.

Expand Down Expand Up @@ -514,7 +514,7 @@ Added in: v1.1.0
* `options` [`<Object>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The following options are supported:

* `startTime` [`<number>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time when the span started. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used
* `exitSpan` [`<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Make an "exit span". Exit spans represent outgoing communication. They are used to create a node in the [Service Map](docs-content://solutions/observability/apps/service-map.md) and a downstream service in the [Dependencies Table](docs-content://solutions/observability/apps/dependencies.md). The provided subtype will be used as the downstream service name.
* `exitSpan` [`<boolean>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Make an "exit span". Exit spans represent outgoing communication. They are used to create a node in the [Service Map](docs-content://solutions/observability/apm/service-map.md) and a downstream service in the [Dependencies Table](docs-content://solutions/observability/apm/dependencies.md). The provided subtype will be used as the downstream service name.
* `links` [`<Array>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Span links. A span can refer to zero or more other transactions or spans (separate from its parent). Span links will be shown in the Kibana APM app trace view. The `links` argument is an array of objects with a single "context" field that is a `Transaction`, `Span`, or W3C trace-context *traceparent* string. For example: `apm.startSpan('aName', { links: [{ context: anotherSpan }] })`.


Expand Down
2 changes: 1 addition & 1 deletion docs/reference/azure-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The Node.js APM Agent can trace function invocations in an [Azure Functions](htt

## Prerequisites [azure-functions-prerequisites]

You need an APM Server to send APM data to. Follow the [APM Quick start](docs-content://solutions/observability/apps/get-started-with-apm.md) if you have not set one up yet. You will need your **APM server URL** and an APM server **secret token** (or **API key**) for configuring the APM agent below.
You need an APM Server to send APM data to. Follow the [APM Quick start](docs-content://solutions/observability/apm/get-started.md) if you have not set one up yet. You will need your **APM server URL** and an APM server **secret token** (or **API key**) for configuring the APM agent below.

You will also need an Azure Function app to monitor. If you do not have an existing one, you can follow [this Azure guide](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-node#create-supporting-azure-resources-for-your-function) to create one.

Expand Down
14 changes: 7 additions & 7 deletions docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ The secret token optionally expected by the APM Server.

The API key optionally expected by the APM Server. This is an alternative to `secretToken`.

This base64-encoded string is used to ensure that only your agents can send data to your APM server. You must have created the API key using the APM server command line tool. Please see the [APM server documentation](docs-content://solutions/observability/apps/api-keys.md) for details on how to do that.
This base64-encoded string is used to ensure that only your agents can send data to your APM server. You must have created the API key using the APM server command line tool. Please see the [APM server documentation](docs-content://solutions/observability/apm/api-keys.md) for details on how to do that.

::::{note}
This feature is fully supported in the APM Server versions >= 7.6.
Expand Down Expand Up @@ -123,7 +123,7 @@ var options = {

The environment name is automatically logged along with all errors and transactions. If you want to overwrite this, use this option.

Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See [environment selector](docs-content://solutions/observability/apps/filter-application-data.md#apm-filter-your-data-service-environment-filter) in the APM app for more information.
Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See [environment selector](docs-content://solutions/observability/apm/filter-data.md#apm-filter-your-data-service-environment-filter) in the APM app for more information.

::::{note}
This feature is fully supported in the APM app in Kibana versions >= 7.2. You must use the query bar to filter for a specific environment in versions prior to 7.2.
Expand Down Expand Up @@ -182,7 +182,7 @@ To configure if outgoing http requests should be instrumented, see [`disableInst
Activate APM Agent Configuration via Kibana. If set to `true`, the client will poll the APM Server regularly for new agent configuration.

::::{note}
This feature requires APM Server v7.3 or later. More information is available in [APM Agent configuration](docs-content://solutions/observability/apps/apm-agent-central-configuration.md).
This feature requires APM Server v7.3 or later. More information is available in [APM Agent configuration](docs-content://solutions/observability/apm/apm-agent-central-configuration.md).
::::


Expand Down Expand Up @@ -629,7 +629,7 @@ The following transaction, span, and error fields will be truncated at this numb
* `span.context.db.statement`
* `error.exception.message`, `error.log.message` - If [`errorMessageMaxLength`](#error-message-max-length) is specified, then that value takes precedence for these error message fields.

Note that tracing data is limited at the upstream APM server to [`max_event_size`](docs-content://solutions/observability/apps/general-configuration-options.md#apm-max_event_size), which defaults to 300kB. If you configure `longFieldMaxLength` too large, it could result in transactions, spans, or errors that are rejected by APM server.
Note that tracing data is limited at the upstream APM server to [`max_event_size`](docs-content://solutions/observability/apm/general-configuration-options.md#apm-max_event_size), which defaults to 300kB. If you configure `longFieldMaxLength` too large, it could result in transactions, spans, or errors that are rejected by APM server.


## `stackTraceLimit` [stack-trace-limit]
Expand Down Expand Up @@ -888,7 +888,7 @@ module.exports = {

Set `breakdownMetrics: false` to disable reporting of breakdown metrics. Note that if `metricsInterval: 0`, then breakdown metrics will not be reported.

Breakdown metrics ([`span.self_time.*`](/reference/metrics.md#metrics-span.self_time.sum)) record the self-time spent in each unique type of span. This data drives the [Time spent by span type](docs-content://solutions/observability/apps/service-overview.md#service-span-duration) chart in the APM app.
Breakdown metrics ([`span.self_time.*`](/reference/metrics.md#metrics-span.self_time.sum)) record the self-time spent in each unique type of span. This data drives the [Time spent by span type](docs-content://solutions/observability/apm/service-overview.md#service-span-duration) chart in the APM app.


## `disableMetrics` [disable-metrics]
Expand Down Expand Up @@ -1025,7 +1025,7 @@ Starting with Elastic Observability 8.2, span links will be visible in trace vie
* **Default:** `true`
* **Env:** `ELASTIC_APM_SPAN_COMPRESSION_ENABLED`

Setting this option to false will disable the [Span compression](docs-content://solutions/observability/apps/spans.md) feature. Span compression reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that some information, such as DB statements of all the compressed spans, will not be collected.
Setting this option to false will disable the [Span compression](docs-content://solutions/observability/apm/spans.md) feature. Span compression reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that some information, such as DB statements of all the compressed spans, will not be collected.

Example usage:

Expand Down Expand Up @@ -1132,6 +1132,6 @@ Change default in v4.0.0, in v3.x the default was `true`
* **Default:** `false`
* **Env:** `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER`

To enable [distributed tracing](docs-content://solutions/observability/apps/traces.md), the agent adds trace context headers to outgoing requests (like HTTP requests, etc.). These headers (`traceparent` and `tracestate`) are defined in the [W3C Trace Context](https://www.w3.org/TR/trace-context-1/) specification.
To enable [distributed tracing](docs-content://solutions/observability/apm/traces.md), the agent adds trace context headers to outgoing requests (like HTTP requests, etc.). These headers (`traceparent` and `tracestate`) are defined in the [W3C Trace Context](https://www.w3.org/TR/trace-context-1/) specification.

When this setting is `true`, the agent will also add the header `elastic-apm-traceparent` for backwards compatibility with older versions of Elastic APM agents. (In the next major version of this APM agent, this setting will default to false.)
2 changes: 1 addition & 1 deletion docs/reference/configuring-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ For information on the available configuration properties and the expected names

Configuration options marked with the ![dynamic config](images/dynamic-config.svg "") badge can be changed at runtime when set from a supported source.

The Node.js Agent supports [Central configuration](docs-content://solutions/observability/apps/apm-agent-central-configuration.md), which allows you to fine-tune certain configurations via the APM app in Kibana. This feature is enabled in the Agent by default, with [`centralConfig`](/reference/configuration.md#central-config).
The Node.js Agent supports [Central configuration](docs-content://solutions/observability/apm/apm-agent-central-configuration.md), which allows you to fine-tune certain configurations via the APM app in Kibana. This feature is enabled in the Agent by default, with [`centralConfig`](/reference/configuration.md#central-config).


## Agent configuration object [agent-configuration-object]
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,5 +20,5 @@ These events, called Transactions and Spans, are sent to the APM Server. The APM

## Additional Components [additional-components]

APM Agents work in conjunction with the [APM Server](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md), [Elasticsearch](docs-content://get-started/index.md), and [Kibana](docs-content://get-started/the-stack.md). The [APM Guide](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md) provides details on how these components work together, and provides a matrix outlining [Agent and Server compatibility](docs-content://solutions/observability/apps/apm-agent-compatibility.md).
APM Agents work in conjunction with the [APM Server](docs-content://solutions/observability/apm/index.md), [Elasticsearch](docs-content://get-started/index.md), and [Kibana](docs-content://get-started/the-stack.md). The [APM Guide](docs-content://solutions/observability/apm/index.md) provides details on how these components work together, and provides a matrix outlining [Agent and Server compatibility](docs-content://solutions/observability/apm/apm-agent-compatibility.md).

Loading
Loading