Symbolicate JavaScript Stack Traces with the OpenTelemetry Collector


Use the symbolicator processor in your OpenTelemetry Collector to symbolicate JavaScript (JS) stack traces.

Important
This feature is in beta, and we would love your feedback!

The symbolicator processor replaces minified names and addresses in your JS stack traces with symbols from provided source maps.

Before You Start 

The symbolicator processor is compatible with Honeycomb OpenTelemetry Web SDK version 0.12.0 and later.

To use the symbolicator 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.

Install 

By default, the Honeycomb OpenTelemetry Collector distribution includes the symbolicator 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 symbolicator processor by adding it to your OpenTelemetry Collector build configuration file:

processors:
  - gomod: github.com/honeycombio/opentelemetry-collector-symbolicator/symbolicatorprocessor v0.0.0
    name: symbolicatorprocessor
    path: ./symbolicatorprocessor

Source Files and Source Maps 

The symbolicator 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.

//# 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:

processors:
  source_map_symbolicator:

You can then configure where your source maps are stored.

Local File Store 

By default, the symbolicator processor loads source map files from a local directory. You can set the file path in your collector configuration:

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

Amazon S3 Store 

Optionally, you can load source files from an Amazon S3 bucket. Add to your OpenTelemetry Collector configuration:

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.

Private Amazon S3 Bucket Authentication 

To use a private Amazon S3 bucket as your file store, set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

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

Google Cloud Storage Store 

Optionally, you can load source files from a Google Cloud Storage (GCS) bucket. Add to your OpenTelemetry Collector configuration:

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.

Private Google Cloud Storage Bucket Authentication 

To use a private Google Cloud Storage bucket as your file store, set the GOOGLE_APPLICATION_CREDENTIALS environment variable.

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: sourcemaps/main.c383b093b0b66825a9c3.js.map

Advanced Configuration 

In addition to basic setup, you can customize how the symbolicator processor handles stack traces by configuring attribute mappings and additional processing options.

Tip
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 symbolicator fails to fully symbolicate the stack trace exception.symbolicator.failed
symbolicator_failure_message_attribute_key Contains the error message if the symbolicator fails to fully symbolicate the stack trace exception.symbolicator.error
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
output_stack_trace_key Which attribute should the symbolicated stack trace be populated into exception.stacktrace
stack_type_key Which attribute contains the exception type exception.type
stack_message_key Which attribute contains the exception message exception.message
preserve_stack_trace After the stack trace has been symbolicated, determines if the original values be preserved as attributes true
original_stack_trace_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 exception.structured_stacktrace.urls.original

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