Details of how spans and traces are sent to BugSnag, including endpoint details.
BugSnag’s trace endpoints conform with the OpenTelemetry protocol (OTLP). They can receive payloads using gRPC (grpc), protobuf-over-http (http/protobuf) and JSON-over-http (http/json).
When sending spans from an OpenTelemetry SDK or Collector, you must include the API key as a subdomain in the URL:
https://<api key>.otlp.bugsnag.com:4317https://<api key>.otlp.bugsnag.com:4318/v1/tracesWhen configuring OpenTelemetry SDKs, you sometimes need to omit the path (/v1/traces) as the SDKs append this. See the per-platform integration guides for details.
The HTTP endpoint can also be accessed on port 443, the default HTTPS port.
<api key> can either be a project-level API key, or an organization-level API key. The project-level API key can be found in Project settings in the BugSnag dashboard. The organization-level endpoint, including API key, is available under Organization settings.
The organization-level API key is designed for use with an OpenTelemetry Collector. When using the organization-level API key, you need to tell BugSnag which project a span should be assigned to - see below.
When sending spans to the organization endpoint, you need to tell BugSnag which project the spans should be assigned to. You do this by making use of the service.name resource attribute. The service.name attribute is required and spans will be rejected if they do not have it set. It can be set in a platform specific way, or usually with the OTEL_SERVICE_NAME environment variable.
To assign service names to projects, go to the Organization Settings > Performance > OpenTelemetry service names.
If your project names usually or sometimes line up with your service names, these can be mapped automatically by enabling “Match Service Name to project name by default”.
For those service names that do not map to a project name, or if you prefer not to use this setting, you can create explicit maps from service names to particular projects in the lower section of the settings page. If there is an explicit mapping here, it will take precedence over any matching project name.
Adding a mapping only affects subsequent spans; already-ingested spans will not be assigned or reassigned to a project.
Spans that are not mapped to projects will show up in distributed trace maps and waterfall diagrams with a “disconnected” icon.
For clientside performance monitoring, using the BugSnag SDKs, we usually recommend configuring a project-level API key, and sending the spans directly to BugSnag. Doing this means BugSnag manages the sample rate for you to meet your managed quota. However if you choose to send your clientside spans to a Collector, the spans will need to be mapped via service name. The BugSnag SDKs set service.name by default (to the app identifier, where available, or to unknown_service). To override this, set the serviceName configuration item in the SDK.
We strongly recommend that you set the service.version and deployment.environment resource attributes, when configuring your SDKs. These correspond directly to the “Release” and “Release stage” properties in BugSnag Errors and using the exact same values (including matching casing) will result in a better experience in BugSnag. Release stage will default to production in BugSnag if you do not set a deployment.environment attribute.
These attributes can be set in code, or you can set them using the OTEL_RESOURCE_ATTRIBUTES environment variable:
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=<release stage>,service.version=<release>"