> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Symbolicate JavaScript Stack Traces with the OpenTelemetry Collector
> Use the source map processor in the OpenTelemetry Collector to resolve minified JavaScript stack traces into readable symbols for easier debugging.
export const FlexStyleTable = ({columns, overflowWrap = "normal", children}) => {
const colWidths = columns ? columns.trim().split(/\s+/) : [];
const scopeKey = [columns || "auto", overflowWrap].join("-").replace(/[^a-zA-Z0-9-]/g, "-");
const colRules = colWidths.map((width, i) => `[data-fst="${scopeKey}"] table th:nth-of-type(${i + 1}) { width: ${width}; }`).join("\n");
const css = `
[data-fst="${scopeKey}"] table {
table-layout: ${colWidths.length > 0 ? "fixed" : "auto"};
width: 100%;
}
${colRules}
[data-fst="${scopeKey}"] table td { overflow-wrap: ${overflowWrap}; }
`.trim();
return
{children}
;
};
Use the sourcemap processor in your OpenTelemetry Collector to symbolicate JavaScript (JS) stack traces.
The [sourcemap processor](https://github.com/honeycombio/opentelemetry-collector-symbolicator?tab=readme-ov-file#javascript-source-maps) replaces minified names and addresses in your JS stack traces with symbols from provided source maps.
## Before You Start
The sourcemap processor is compatible with [Honeycomb OpenTelemetry Web SDK](https://github.com/honeycombio/honeycomb-opentelemetry-web) version 0.12.0 and later.
To use the sourcemap processor, you need:
* OpenTelemetry Collector built with `CGO` enabled.
* An environment or container image with `glibc` support.
We recommend `gcr.io/distroless/cc`, a secure and lightweight container image with CGO and `glibc` support.
If you're not using the Honeycomb OpenTelemetry Web SDK, make sure your exception data is in [the format the processor expects](https://github.com/honeycombio/opentelemetry-collector-symbolicator/blob/main/README.md#exception-information-format).
## Install
By default, the [Honeycomb OpenTelemetry Collector distribution](https://github.com/honeycombio/honeycomb-collector-distro) includes the sourcemap processor, so you can skip to the next section if you're using it. If you use another collector distribution or build your own, it must be built with CGO enabled.
You can install the sourcemap processor by adding it to your OpenTelemetry Collector build configuration file:
```yaml theme={}
processors:
- gomod: github.com/honeycombio/opentelemetry-collector-symbolicator/sourcemapprocessor v0.0.14
```
You can find the latest sourcemap processor version on the [releases page](https://github.com/honeycombio/opentelemetry-collector-symbolicator/releases) in the GitHub repo.
## Source Files and Source Maps
The sourcemap processor requires access to your minimized JS source files and associated source maps. These can be stored in your local file system, Amazon S3, or Google Cloud Storage.
To support symbolication, your minified source files must have a comment with a `sourceMappingURL` pointing to the relative path of the source map file.
```js theme={}
//# sourceMappingURL=/static/dist/main.c383b093b0b66825a9c3.js.map
```
You should also version your source files and source maps with a file hash in the file name, for example: `vendor.1c285a50f5307be9648d.js`.
This helps prevent conflicts and ensure the correct file versions are used.
## Configure a File Store
Add the `source_map_symbolicator` as a processor in your OpenTelemetry Collector configuration:
```yaml theme={}
processors:
source_map_symbolicator:
```
You can then configure where your source maps are stored.
By default, the sourcemap processor loads source map files from a local directory.
You can set the file path in your collector configuration:
```yaml theme={}
processors:
source_map_symbolicator:
# source_map_store is sets which store to use, in this case local disk
source_map_store: file_store
local_source_maps:
# (optional) path sets the base path of the files, defaults to `.`
path: /tmp/sourcemaps
```
Make sure your collector can access the `path` directory you set, and that file paths in stack traces match the structure of your configured file store.
#### How the Processor Retrieves Files from Local Disk
When retrieving files from local disk, the processor:
1. Gets the base file name from the URL included in the stack trace.
2. The `path`, if configured, is joined with the base file name.
3. Reads the file using the joined path from disk.
For example:
* Original URL: `https://example.com/static/dist/main.c383b093b0b66825a9c3.js`
* `path` is set to `/tmp/sourcemaps`
* New path: `/tmp/sourcemaps/main.c383b093b0b66825a9c3.js.map`
Optionally, you can load source maps from an Amazon S3 bucket.
Add to your OpenTelemetry Collector configuration:
```yaml theme={}
processors:
source_map_symbolicator:
# source_map_store sets which store to use, in this case S3
source_map_store: s3_store
s3_source_maps:
# name of the bucket the files are stored in
bucket: source-maps-bucket
# (optional) the bucket's region
region: us-east-1
# (optional) prefix is used to nest the files in a sub key of the bucket
prefix: source-maps
```
Make sure your collector has permission to access the S3 bucket.
Also, ensure the file paths in stack traces match the structure used in your file store.
#### How the Processor Retrieves Files from S3
When retrieving files from an Amazon S3 bucket, the processor:
1. Gets the base file name from the URL included in the stack trace.
2. The `prefix`, if configured, is joined with the base file name.
3. Uses this joined path as the key to retrieve the file from the bucket.
For example:
* Original URL: `https://example.com/static/dist/main.c383b093b0b66825a9c3.js`
* `prefix` is set to `source-maps`
* New path: `sourcemaps/main.c383b093b0b66825a9c3.js.map`
Optionally, you can load source maps from a Google Cloud Storage (GCS) bucket.
Add to your OpenTelemetry Collector configuration:
```yaml theme={}
processors:
source_map_symbolicator:
# source_map_store sets which store to use, in this case GCS
source_map_store: gcs_store
gcs_source_maps:
# the name of the bucket the files are stored in
bucket: source-maps-bucket
# (optional) prefix is used to nest the files in a sub key of the bucket
prefix: source-maps
```
Make sure your collector has permission to access the GCS bucket.
Also, ensure the file paths in stack traces match the structure used in your file store.
#### How the Processor Retrieves Files from GCS
When retrieving files from a Google Cloud Storage bucket, the processor:
1. Gets the base file name from the URL included in the stack trace.
2. The `prefix`, if configured, is joined with the base file name.
3. Uses this joined path as the key to retrieve the file from the bucket.
For example:
* Original URL: `https://example.com/static/dist/main.c383b093b0b66825a9c3.js`
* `prefix` is set to `source-maps`
* New path: `source-maps/main.c383b093b0b66825a9c3.js.map`
## Advanced Configuration
In addition to basic setup, you can customize how the sourcemap processor handles stack traces by configuring attribute mappings and additional processing options.
After updating the configuration file, restart the OpenTelemetry Collector to apply the changes.
### Mapping Attributes
Use these configuration options to specify which attributes the processor should read from and write to when handling stack traces:
| Config Key | Description | Example Value |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `symbolicator_failure_attribute_key` | Signals if the the symbolicator fails to fully symbolicate the stack trace | `exception.symbolicator.failed` |
| `symbolicator_error_attribute_key` | Contains the error message if the the symbolicator fails to fully symbolicate the stack trace | `exception.symbolicator.error` |
| `symbolicator_parsing_method_attribute_key` | Stores the stack trace parsing method used by the processor | `exception.symbolicator.parsing_method` |
| `columns_attribute_key` | Which attribute should the columns of the stack trace be sourced from | `exception.structured_stacktrace.columns` |
| `functions_attribute_key` | Which attribute should the functions of the stack trace be sourced from | `exception.structured_stacktrace.functions` |
| `lines_attribute_key` | Which attribute should the lines of the stack trace be sourced from | `exception.structured_stacktrace.lines` |
| `urls_attribute_key` | Which attribute should the urls of the stack trace be sourced from | `exception.structured_stacktrace.urls` |
| `stack_trace_attribute_key` | Which attribute should the symbolicated stack trace be populated into | `exception.stacktrace` |
| `exception_type_attribute_key` | Which attribute contains the exception type | `exception.type` |
| `exception_message_attribute_key` | Which attribute contains the exception message | `exception.message` |
| `preserve_stack_trace` | After the stack trace has been symbolicated should the original values be preserved as attributes | `true` |
| `original_stack_trace_attribute_key` | If the stack trace is being preserved which key should it be copied to | `exception.stacktrace.original` |
| `original_columns_attribute_key` | If the stack trace is being preserved which key should the functions be copied to | `exception.structured_stacktrace.functions.original` |
| `original_functions_attribute_key` | If the stack trace is being preserved which key should the lines be copied to | `exception.structured_stacktrace.lines.original` |
| `original_lines_attribute_key` | If the stack trace is being preserved which key should the columns be copied to | `exception.structured_stacktrace.columns.original` |
| `original_urls_attribute_key` | If the stack trace is being preserved which key should the urls be copied to | |
### Additional Processing Options
Use these configuration options to control how stack traces are processed and managed:
| Config Key | Description | Example Value |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------- |
| `timeout` | Maximum time (in seconds) to wait for symbolication before timing out. | `5` |
| `source_map_cache_size` | Maximum number of source maps to cache in memory. Reduce this value if the Collector encounters memory constraints. | `128` |
### Language-Based Routing
The source map processor supports language-based routing to ensure it only processes signals from JavaScript/TypeScript applications. This prevents the processor from running on signals from other languages (like Java or Swift), improving performance and avoiding unnecessary processing.
| Config Key | Description | Default Value | Example Values |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------- |
| `language_attribute_key` | The attribute key that contains the programming language or SDK language of the telemetry signal. | `telemetry.sdk.language` | `telemetry.sdk.language` |
| `allowed_languages` | A list of language values that this processor will handle. If the signal's language attribute matches any value in this list, the processor will run. If empty (default), the processor will process all signals regardless of language. **Important:** When `allowed_languages` is configured, signals without a language attribute will be skipped. | `[]` (empty, processes all) | `["javascript", "webjs", "hermesjs"]` |
If using Honeycomb's React Native SDK, you'll want to enable `hermesjs` as a value. See the [SDK's default attribute values](https://github.com/honeycombio/honeycomb-opentelemetry-react-native/tree/main?tab=readme-ov-file#default-attributes)
**Example configuration:**
```yaml theme={}
processors:
source_map_symbolicator:
allowed_languages: ["javascript", "webjs"]
```
`allowed_languages` configuration behavior:
* Empty `allowed_languages` (default): Processes all signals, regardless of language attribute.
* With `allowed_languages` configured: Only processes signals where the language attribute matches one of the allowed values (case-insensitive).
* Missing language attribute: Skips processing when `allowed_languages` is configured.