Send OpenTelemetry data from a Golang app to Axiom

go get go.opentelemetry.io/otel
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp
go get go.opentelemetry.io/otel/sdk/resource
go get go.opentelemetry.io/otel/sdk/trace
go get go.opentelemetry.io/otel/semconv/v1.24.0
go get go.opentelemetry.io/otel/trace
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
go get go.opentelemetry.io/otel/propagation

go mod init <module-name>

go mod tidy

// main.go

package main

import (
   "context" // For managing request-scoped values, cancellation signals, and deadlines.
   "fmt" // For formatted I/O operations.
   "log" // For logging errors and information.
   "math/rand" // For generating pseudo-random numbers.
   "net" // For network I/O interfaces.
   "net/http" // For HTTP server and client operations.
   "os" // For platform-independent interface to operating system features.
   "os/signal" // For handling OS signals.
   "time" // For time-related operations.

   // OpenTelemetry imports for tracing and observability.
   "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp" // OpenTelemetry instrumentation for net/http.
   "go.opentelemetry.io/otel" // Core OpenTelemetry APIs for tracing.
)

func main() {
   // Main function serves as the entry point of the application
   if err := run(); err != nil {
       log.Fatalln(err) // Logs fatal errors and exits the application
   }
}

func run() error {
   // Context to handle interrupt signals for a graceful shutdown
   ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
   defer stop() // Ensures the stop function is called on exit

   otelShutdown, err := SetupTracer() // Initializes OpenTelemetry tracing
   if err != nil {
       return err
   }
   defer func() { // Deferred function to handle OpenTelemetry shutdown
       if shutdownErr := otelShutdown(ctx); shutdownErr != nil {
           log.Printf("failed to shutdown OpenTelemetry: %v", shutdownErr)
       }
   }()

   // Configuration of the HTTP server
   srv := &http.Server{
       Addr:         ":8080",               // Server address
       BaseContext:  func(_ net.Listener) context.Context { return ctx },
       ReadTimeout:  5 * time.Second,       // Server read timeout
       WriteTimeout: 15 * time.Second,      // Server write timeout
       Handler:      newHTTPHandler(),      // HTTP handler
   }

   // Start server in a goroutine to handle requests concurrently
   go func() {
       if err := srv.ListenAndServe(); err != http.ErrServerClosed {
           log.Fatalf("HTTP server ListenAndServe: %v", err) // Log fatal errors during server startup
       }
   }()

   <-ctx.Done() // Wait for interrupt signal

   // Shutdown the server with a timeout for graceful exit
   shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
   defer cancel() // Ensures cancel function is called on exit
   if err := srv.Shutdown(shutdownCtx); err != nil {
       log.Fatalf("HTTP server Shutdown: %v", err) // Log fatal errors during server shutdown
   }

   return nil
}

func newHTTPHandler() http.Handler {
   mux := http.NewServeMux() // HTTP request multiplexer

   // Function to handle specific routes with OpenTelemetry instrumentation
   handleFunc := func(pattern string, handlerFunc func(http.ResponseWriter, *http.Request)) {
       handler := otelhttp.WithRouteTag(pattern, http.HandlerFunc(handlerFunc))
       mux.Handle(pattern, handler) // Associate pattern with handler
   }

   handleFunc("/rolldice", rolldice) // Setup route for rolldice

   handler := otelhttp.NewHandler(mux, "/")
   return handler
}

func rolldice(w http.ResponseWriter, r *http.Request) {
   _, span := otel.Tracer("example-tracer").Start(r.Context(), "rolldice")
   defer span.End() // Ensure span ends after function execution

   randGen := rand.New(rand.NewSource(time.Now().UnixNano())) // Local random generator for thread safety
   roll := 1 + randGen.Intn(6) // Simulate dice roll

   fmt.Fprintf(w, "Rolled a dice: %d\n", roll) // Send the result back to the client
}

package main

import (
   "context" // For managing request-scoped values, cancellation signals, and deadlines.
   "crypto/tls" // For configuring TLS options, like certificates.

   // OpenTelemetry imports for setting up tracing and exporting telemetry data.
   "go.opentelemetry.io/otel" // Core OpenTelemetry APIs for managing tracers.
   "go.opentelemetry.io/otel/attribute" // For creating and managing trace attributes.
   "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" // HTTP trace exporter for OpenTelemetry Protocol (OTLP).
   "go.opentelemetry.io/otel/propagation" // For managing context propagation formats.
   "go.opentelemetry.io/otel/sdk/resource" // For defining resources that describe an entity producing telemetry.
   "go.opentelemetry.io/otel/sdk/trace" // For configuring tracing, like sampling and processors.
   semconv "go.opentelemetry.io/otel/semconv/v1.24.0" // Semantic conventions for resource attributes.
)

const (
   serviceName           = "axiom-go-otel" // Name of the service for tracing.
   serviceVersion        = "0.1.0" // Version of the service.
   otlpEndpoint          = "api.axiom.co" // OTLP collector endpoint.
   bearerToken           = "Bearer $API_TOKEN" // Authorization token.
   deploymentEnvironment = "production" // Deployment environment.
)

func SetupTracer() (func(context.Context) error, error) {
   ctx := context.Background()
   return InstallExportPipeline(ctx) // Setup and return the export pipeline for telemetry data.
}

func Resource() *resource.Resource {
   // Defines resource with service name, version, and environment.
   return resource.NewWithAttributes(
       semconv.SchemaURL,
       semconv.ServiceNameKey.String(serviceName),
       semconv.ServiceVersionKey.String(serviceVersion),
       attribute.String("environment", deploymentEnvironment),
   )
}

func InstallExportPipeline(ctx context.Context) (func(context.Context) error, error) {
   // Sets up OTLP HTTP exporter with endpoint, headers, and TLS config.
   exporter, err := otlptracehttp.New(ctx,
       otlptracehttp.WithEndpoint(otlpEndpoint),
       otlptracehttp.WithHeaders(map[string]string{
           "Authorization":   bearerToken,
           "X-AXIOM-DATASET": "$DATASET_NAME",
       }),
       otlptracehttp.WithTLSClientConfig(&tls.Config{}),
   )
   if err != nil {
       return nil, err
   }

   // Configures the tracer provider with the exporter and resource.
   tracerProvider := trace.NewTracerProvider(
       trace.WithBatcher(exporter),
       trace.WithResource(Resource()),
   )
   otel.SetTracerProvider(tracerProvider)

   // Sets global propagator to W3C Trace Context and Baggage.
   otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
       propagation.TraceContext{},
       propagation.Baggage{},
   ))

   return tracerProvider.Shutdown, nil // Returns a function to shut down the tracer provider.
}

http://localhost:8080/rolldice

tracer := otel.Tracer("serviceName")

ctx, span := tracer.Start(context.Background(), "operationName")
defer span.End()
// Perform the operation here

span.SetAttributes(attribute.String("key", "value"))
span.AddEvent("eventName", trace.WithAttributes(attribute.String("key", "value")))

import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"

http.Handle("/path", otelhttp.NewHandler(handler, "operationName"))