Skip to main content
Use the dSym processor in your OpenTelemetry Collector to symbolicate iOS stack traces. The dSym processor replaces obfuscated names and addresses in your iOS stack traces with symbols from provided dSYM files.

​
Before You Start

The dSym processor is compatible with Honeycomb OpenTelemetry Swift SDK version 0.0.14 and later. To use the dSym 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 Swift 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/dsymprocessor v0.0.9
You can find the latest dSym processor version on the releases page in the GitHub repo.

​
dSYM Files

The dSym processor requires access to the dSYM file generated by your build process. This file can be stored in your local file system, Amazon S3, or Google Cloud Storage. To support symbolication, your dSYM file must be versioned with the generated build UUID in the file name. For example: 6A8CB813-45F6-3652-AD33-778FD1EAB196.dSYM.

​
Getting the Build UUID

You can use the dwarfdump tool to get the build UUID from an an .xcarchive file generated by Xcode. The following example script finds the latest build and uploads it to the app-archives Amazon S3 bucket with the ios prefix. 
# Get the App Name
if [[ -z "$1" ]]; then
  echo "❌ Usage: $0 <TargetName>"
  exit 1
fi

TARGET_NAME=$1

export ARCHIVE_PATH=$(ls -dt ~/Library/Developer/Xcode/Archives/*/"$TARGET_NAME"*.xcarchive | head -1)
echo "📦 Using Archive Path: $ARCHIVE_PATH"

if [[ ! -d "$ARCHIVE_PATH" ]]; then
  echo "❌ Archive not found for target: $TARGET_NAME! Please archive the project first in Xcode."
  exit 1
fi

find "$ARCHIVE_PATH/dSYMs" -name "*.dSYM" | while read line ; do
   echo "🔍 Found dsym at: $line"
   dsymuuid=$(dwarfdump -u "$line" | awk '{ print $2 }').dSYM
   echo "⬆️ Uploading dsym to: $dsymuuid"
   aws s3 cp --recursive "$line" s3://app-archives/ios/$dsymuuid
done

​
Configure a File Store

Add the dsym_symbolicator as a processor in your OpenTelemetry Collector configuration: 
processors:
  dsym_symbolicator:
You can then configure where your source maps are stored.
By default, the dSym processor loads dSYM files from a local directory. You can set the file path in your collector configuration:
processors:
  dsym_symbolicator:
    # dsym_store is sets which store to use, in this case local disk
    dsym_store: file_store
    local_dsyms:
        # (optional) path sets the base path of the files, defaults to `.`
        path: /tmp/dsyms
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.

​
Advanced Configuration

In addition to basic setup, you can customize how the dSym 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:

​
Additional Processing Options

Use these configuration options to control how stack traces are processed and managed:

​
Language-Based Routing

The dSYM processor supports language-based routing to ensure it only processes signals from iOS/macOS applications. This prevents the processor from running on signals from other platforms (like Android or JavaScript), improving performance and avoiding unnecessary processing. Example configuration: 
processors:
  dsym_symbolicator:
    allowed_languages: ["swift", "ios"]
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.