The bugsnagperformance package is a plugin for the OpenTelemetry SDK to make it simple to send your spans to your BugSnag dashboard. The guide provides more detail on how it can be configured for your application.
To set configuration options, call bugsnagperformance.Configure() passing it a bugsnagperformance.Configuration struct:
import "github.com/bugsnag/bugsnag-go-performance"
bugsnagperformance.Configure(bugsnagperformance.Configuration{
APIKey: "YOUR_API_KEY_HERE",
AppVersion: 1.0.0,
})
The only required configuration is the BugSnag API key. We also recommend you set the AppVersion and ReleaseStage if these make sense for your deployment workflow.
Where possible, these configuration options can also be set by environment variables. If you use environment variables to configure the BugSnag Error Monitoring library for Go, then the Performance package will also pick up the applicable values. You can also configure different values by setting the BUGSNAG_PERFORMANCE_ equivalent (e.g. BUGSNAG_PERFORMANCE_API_KEY).
You can find your API key in Project Settings from your BugSnag dashboard.
API key can be loaded from the environment variables BUGSNAG_API_KEY/BUGSNAG_PERFORMANCE_API_KEY or specified in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
APIKey: "YOUR_API_KEY_HERE",
})
Setting your app’s version information in configuration allows you to see performance data for a specific release.
App version can be loaded from the environment variables BUGSNAG_APP_VERSION/BUGSNAG_PERFORMANCE_APP_VERSION or specified in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
AppVersion: "1.2.3",
})
By default, the plugin uses BugSnag’s sampling mechanism to spread the span quota in your plan over a month with a constantly adjusted probability that a given trace will be sampled. If you are controlling the sampling yourself – such as using an OpenTelemetry Collector – a separate trace.Sampler can be provided.
A custom sampler can be set via the OpenTelemetry configuration option OTEL_TRACES_SAMPLER or specified in code:
import "go.opentelemetry.io/otel/sdk/trace"
bugsnagperformance.Configure(bugsnagperformance.Configuration{
CustomSampler: trace.AlwaysSample(),
})
When a sampling probability is set explicitly, the captured spans will be counted towards your unmanaged quota. See the sampling guide for details.
By default we will send trace and span data to the bugsnag.com web service address for traces.
If you are using BugSnag On-premise you’ll need to set this to your Trace Server endpoint.
Endpoints can be loaded from the environment variable BUGSNAG_PERFORMANCE_ENDPOINT or specified in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
Endpoint: "http://bugsnag.internal:4318/v1/traces",
})
By default, log messages from the bugsnagperformance package will be logged using the global logger.
You can override this by setting the Logger configuration option in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
Logger: app.Logger,
})
For improved shutdown handling, set the MainContext configuration option passing the main context of your application.
The context is used to control the lifecycle of the event sending goroutine. When the MainContext is marked as Done, an attempt is made to send the remaining events and the goroutine exits gracefully.
You can specify this configuration option in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
MainContext: ctx,
}
Setting a release stage in your configuration allows you to filter performance data by different stages of the application release process (development, production, etc) in the BugSnag dashboard. The release stage is set to “production” by default.
Release stage can be loaded from the environment variables BUGSNAG_RELEASE_STAGE/BUGSNAG_PERFORMANCE_RELEASE_STAGE or specified in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
ReleaseStage: "development",
})
You can also limit which builds send performance data by setting the enabledReleaseStages configuration option.
EnabledReleaseStages can be loaded as a comma-delimited list from the environment variables BUGSNAG_RELEASE_STAGE/BUGSNAG_PERFORMANCE_RELEASE_STAGE or specified in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
EnabledReleaseStages: []string{"production", "staging"},
})
The plugin will merge some available data (e.g. the configured app version) to the resource attributes sent with span data to make it available on the BugSnag dashboard. This will contain any data that you have set using the OTEL_RESOURCE_ATTRIBUTES environment variable.
If you wish to set resource attributes in code, you should add the Resource as the Resource configuration option and it will be used instead of the default:
import "go.opentelemetry.io/otel/sdk/resource"
bugsnagperformance.Configure(bugsnagperformance.Configuration{
Resource: resource.NewWithAttributes(resource.NewSchemaless([]attribute.KeyValue{
{
Key: attribute.Key("device.id"),
Value: attribute.StringValue(deviceID),
},
}))
})
The service name provides a human-readable identifier for the app generating the spans. This is shown in Distributed Tracing to differentiate spans across the distributed trace.
The service name can be loaded from the environment variable BUGSNAG_PERFORMANCE_SERVICE_NAME or specified in code:
bugsnagperformance.Configure(bugsnagperformance.Configuration{
ServiceName: "WidgetProcessor",
})