Go Custom Instrumentation

AppSignal is compatible with OpenTelemetry instrumentation packages. Some of these instrumentation packages may require additional setup. This does not always include the information you need to debug issues. For more fine-grained reporting, you can add custom instrumentation. We support OpenTelemetry tracing as laid out in the OpenTelemetry documentation. It’s possible to add more data to span using OpenTelemetry span attributes. There are also AppSignal span attributes that can change how traces are grouped and some attributes that allow for filtering out sensitive data.

Setup

When adding custom instrumentation, first import the OpenTelemetry trace package in the file you want to add the instrumentation to.

import (
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/trace"
)

Creating a new span

Using the tracer initialized during the installation, create a new span.

var tracer = otel.Tracer("my-tracer-name")

func httpHandler(w http.ResponseWriter, r *http.Request) {
	// Create a new span from the parent context
	ctx, span := tracer.Start(r.Context(), "hello-span")
	// Defer closing the span to the end of this function
	defer span.End()

	// Set attributes
}

Note: In these examples we’re relying on the context from the HTTP request, given by r.Context(). Receiving the context may be different in your application.

Get the current span

You can also fetch the current span using the tracer initialized during the installation:

func httpHandler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()
    span := trace.SpanFromContext(ctx)

	// Set attributes
}

Note: This will only return a span if one is already active. More ways to create and get spans are documented on the OpenTelemetry Go Instrumentation page.

AppSignal attributes

Once you have created, or fetched, a span, you can set certain attributes that are specific to AppSignal to customize how the data arrives in AppSignal.

span = // Create a new span or fetch the current span
span.SetAttributes(attribute.String("attribute_name", "attribute value"))

See our guides for more information on what custom AppSignal attributes are supported:

Report errors

To report an error, record it on a span with the OpenTelemetry RecordError method. Pass trace.WithStackTrace(true) to include the stack trace. You can also set the span’s status to Error with SetStatus.

import (
	"go.opentelemetry.io/otel/codes"
	"go.opentelemetry.io/otel/trace"
)

func httpHandler(w http.ResponseWriter, r *http.Request) {
	span := trace.SpanFromContext(r.Context())

	if err := processOrder(r); err != nil {
		// Record the error, including its stack trace
		span.RecordError(err, trace.WithStackTrace(true))
		// Set the span's status to Error
		span.SetStatus(codes.Error, err.Error())

		http.Error(w, "Could not process the order", http.StatusInternalServerError)
		return
	}
}

RecordError adds an exception event to the span with the error’s type and message, plus its stack trace when you pass trace.WithStackTrace(true). AppSignal reports these exception events as errors when they’re recorded on the root span of your service’s part of the trace, such as the span for an incoming HTTP request. To stop AppSignal from reporting an error, add its type to the ignore_errors list. The type is the Go type of the error, and AppSignal also shows it as the error’s name. For example, every error created with errors.New has the type *errors.errorString, so adding that type ignores all of them.

Report an error from a child span

AppSignal only reports an error recorded on a child span, such as a span you created inside a request, when you add the appsignal.alert_this_error attribute set to true:

func httpHandler(w http.ResponseWriter, r *http.Request) {
	ctx, span := tracer.Start(r.Context(), "charge_payment")
	defer span.End()

	if err := chargePayment(ctx, r); err != nil {
		span.RecordError(err,
			trace.WithStackTrace(true),
			trace.WithAttributes(attribute.Bool("appsignal.alert_this_error", true)),
		)
		span.SetStatus(codes.Error, err.Error())

		http.Error(w, "Could not charge the payment", http.StatusInternalServerError)
		return
	}
}

Report an error outside a request

For code that doesn’t run inside a request, such as a background job, start a new span from context.Background(). This span is the root span of a new trace, so AppSignal reports errors recorded on it:

func syncInventory() {
	ctx, span := tracer.Start(context.Background(), "sync_inventory")
	defer span.End()

	if err := fetchStockLevels(ctx); err != nil {
		span.RecordError(err, trace.WithStackTrace(true))
		span.SetStatus(codes.Error, err.Error())
	}
}

SDKs & telemetry

Language SDKs

Telemetry tools