OpenTelemetry Collector Symbolicator Processor

An open telemetry collector processor that will symbolicate JavaScript stack traces using source maps. This is compatible with v0.12.0 and onwards of the Honeycomb OpenTelemetry web SDK.

To install this processor, include it in the build config file of your OpenTelemetry collector distro. You can also use the pre-built Honeycomb OpenTelemetry collector distro that already includes this processor.

Requirements

• We require the use of CGO for the processor. If you are building your own collector image it must support glibc. We recommend gcr.io/distroless/cc

Basic Configuration

Register the plugin in the processors section of your open telemetry collector configuration.

    processors:
      symbolicator:

JavaScript source and source map files

The symbolicator requires access to both your minimised JavaScript source files and associated JavaScript source map files generated by your build process. Ideally these files are versioned with a file hash in the file name. eg. main.c383b093b0b66825a9c3.js. The minimised source file must also contain the sourceMappingURL tag containing the relative path to the source map file. The symbolicator can access these files through a number of different storage mechanisms documented below.

File Store

The default configuration will load the source(map) files (this must include both the JavaScript source file and the JavaScript source map file) from a local path on disk. You can set the base path that will be used.

    processors:
      symbolicator:
        # source_map_store is used to configure which store to use, in this case local disk
        source_map_store: file_store
        local_source_maps:
          # (optional) path is used to set the base path of the files, defaults to `.`
          path: /tmp/sourcemaps

How does the file store source the files?

Each line of the stack trace includes the URL of the file it originated from. Taking this as an example https://example.com/static/dist/main.c383b093b0b66825a9c3.js. The base file name is then found main.c383b093b0b66825a9c3.js. This path is joined with the configured path and then read from disk.

S3 Store

You can also load the source(map) files (this must include both the JavaScript source file and the JavaScript source map file) from an S3 bucket.

    processors:
      symbolicator:
        # source_map_store is used to configure which store to use, in this case S3
        source_map_store: s3_store
        # s3_source_maps is used to configure the sourcing of source maps from S3
        s3_source_maps:
          # bucket is the name of the bucket the files are stored in
          bucket: source-maps-bucket
          # (optional) region is used to configure the buckets location
          region: us-east-1
          # (optional) prefix is used to nest the files in a sub key of the bucket
          prefix: source-maps

How does the S3 store source the files?

Each line of the stack trace includes the URL of the file it originated from. Taking this as an example https://example.com/static/dist/main.c383b093b0b66825a9c3.js. The base file name is then found main.c383b093b0b66825a9c3.js. This path is joined with the prefix if provided and then used as the key to source from the bucket.

GCS Store

You can also load the source(map) files from a GCS bucket.

    processors:
      symbolicator:
        # source_map_store is used to configure which store to use, in this case GCS
        source_map_store: gcs_store
        # gcs_source_maps is used to configure the sourcing of source maps from GCS
        gcs_source_maps:
          # bucket is 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

How does the GCS store source the files?

Each line of the stack trace includes the URL of the file it originated from. Taking this as an example https://example.com/static/dist/main.c383b093b0b66825a9c3.js. The base file name is then found main.c383b093b0b66825a9c3.js. This path is joined with the prefix if provided and then used as the key to source from the bucket.

Exception information format

The processor expects the stacktrace information to be formatted into four separate attributes:

• columns
• functions
• lines
• urls

Each of these attributes must be a slice with each being of equal length.

Example:

columns: [6465,3512358,3512661,3514018,758545]
functions: ["?","w.callback","push.Br+g.w.crossDomainError","XMLHttpRequest.<anonymous>","XMLHttpRequest.<anonymous>"]
lines: [3582,2,2,2,2]
urls: ["https://example.com/static/dist/main.c383b093b0b66825a9c3.js","https://example.com/static/dist/vendor.1c285a50f5307be9648d.js","https://example.com/static/dist/vendor.1c285a50f5307be9648d.js","https://example.com/static/dist/vendor.1c285a50f5307be9648d.js","https://example.com/static/dist/vendor.1c285a50f5307be9648d.js"]

Advanced Configuration

Attribute Mapping

The following configuration options can also be provided to change the attributes used to look for stack traces and store them.

Config Key	Description	Example Value
symbolicator_failure_attribute_key	Signals if the the symbolicator fails to fully symbolicate the stack trace	exception.symbolicator.failed
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 should 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 Options

Config Key	Description	Example Value
timeout	Max duration to wait to symbolicate a stack trace in seconds.	5
source_map_cache_size	The maximum number of source maps to cache. Reduce this if you are running into memory issues with the collector.	128