Add OTEL instrumentation docs for Go

Signed-off-by: Han Verstraete (OpenFaaS Ltd) <[email protected]>

Author: welteki

docs/edge/open-telemetry.md

@@ -76,4 +76,4 @@ Checkout the docs for more details on [how to configure Grafana Alloy to collect
 
 Functions and services deployed on OpenFaaS Edge can use the service name when configuring the telemetry collection endpoint e,g. `alloy:4317` or `alloy:4318`. 
 
-For more info on how to instrument and configure telemetry for functions checkout our language guides for: [Python](/languages/python/#opentelemetry-zero-code-instrumentation) or [Node.js](/languages/node/#opentelemetry-zero-code-instrumentation).
+For more info on how to instrument and configure telemetry for functions checkout our language guides for: [Python](/languages/python/#opentelemetry-zero-code-instrumentation), [Node.js](/languages/node/#opentelemetry-zero-code-instrumentation) or [Go](/languages/go/#opentelemetry-instrumentation)

docs/languages/go.md

@@ -402,3 +402,249 @@ func Handle(w http.ResponseWriter, r *http.Request) {
 }
 ```
 
+## OpenTelemetry instrumentation
+
+To instrument a Go function it is recommended to modify one of the existing Go templates. This will allow you to instrument the HTTP server and handle shutdown for the OpenTelemetry SDK properly.
+
+There are two ways to [customise a template](/cli/templates/#how-to-customise-a-template):
+
+- Fork the template repository and modify the template. Recommended method that allows for distribution and reuse of the template.
+- Pull the template and apply patches directly in the `./template/<language_name>` directory. Good for quick iteration and experimentation with template modifications. The modified template cannot be shared and reused. Changes may get overwritten when pulling templates again.
+
+In this example we are going to modify the [`golang-middleware` template](https://github.com/openfaas/golang-http-template).
+
+Ensure the right packages are added in the template `go.mod`:
+
+```sh
+go get go.opentelemetry.io/otel \
+  go.opentelemetry.io/otel/trace \
+  go.opentelemetry.io/otel/sdk \
+  go.opentelemetry.io/otel/exporters/stdout/stdouttrace \
+  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc \
+  go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
+```
+
+Modify the `main.go` file of the template to include code that sets up the OpenTelemetry SDK and instruments the HTTP server.
+
+```diff
+func main() {
++	ctx := context.Background()
++
++   // Create exporters by reading the exporter configuration from env variables.
++	exporters, err := getExporters(ctx)
++	if err != nil {
++		log.Fatalf("failed to initialize exporters: %v", err)
++	}
++
++	// Create a new tracer provider with a batch span processor and the given exporters.
++	tp := newTracerProvider(exporters)
++	otel.SetTracerProvider(tp)
++
++	// Handle shutdown properly so nothing leaks.
++	defer func() { _ = tp.Shutdown(ctx) }()
++
+	readTimeout := parseIntOrDurationValue(os.Getenv("read_timeout"), defaultTimeout)
+	writeTimeout := parseIntOrDurationValue(os.Getenv("write_timeout"), defaultTimeout)
+	healthInterval := parseIntOrDurationValue(os.Getenv("healthcheck_interval"), writeTimeout)
+
+	s := &http.Server{
+		Addr:           fmt.Sprintf(":%d", 8082),
+		ReadTimeout:    readTimeout,
+		WriteTimeout:   writeTimeout,
+		MaxHeaderBytes: 1 << 20, // Max header of 1MB
+	}
+
+- 	http.HandleFunc("/", function.Handle)
++	http.Handle("/", otelhttp.NewHandler(http.HandlerFunc(function.Handle), ""))
+
+	listenUntilShutdown(s, healthInterval, writeTimeout)
+}
+```
+
+The `getExporters` function creates and returns a list of exporters. The configuration for the exporter is read from environment variables. This makes it easy to later configure the exporters through the `stack.yaml` file of functions that use the template.
+
+By default we support console and OTLP over gRPC exporters but you can modify this function to create your preferred exporters with specific configuration if that is required.
+
+```go
+func getExporters(ctx context.Context) ([]sdktrace.SpanExporter, error) {
+	var exporters []sdktrace.SpanExporter
+
+	exporterTypes := os.Getenv("OTEL_TRACES_EXPORTER")
+	if exporterTypes == "" {
+		exporterTypes = "stdout"
+	}
+
+	insecureValue := os.Getenv("OTEL_EXPORTER_OTLP_TRACES_INSECURE")
+	insecure, err := strconv.ParseBool(insecureValue)
+	if err != nil {
+		insecure = false
+	}
+
+	for _, exp := range strings.Split(exporterTypes, ",") {
+		switch exp {
+		case "console":
+			exporter, err := stdouttrace.New(stdouttrace.WithPrettyPrint())
+			if err != nil {
+				return nil, err
+			}
+
+			exporters = append(exporters, exporter)
+		case "otlp":
+			endpoint := os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+			if endpoint == "" {
+				endpoint = "0.0.0.0:4317"
+			}
+
+			opts := []otlptracegrpc.Option{
+				otlptracegrpc.WithEndpoint(endpoint),
+				otlptracegrpc.WithDialOption(grpc.WithBlock()),
+			}
+
+			if insecure {
+				opts = append(opts, otlptracegrpc.WithInsecure())
+
+			}
+
+			exporter, err := otlptracegrpc.New(ctx, opts...)
+			if err != nil {
+				return nil, err
+			}
+
+			exporters = append(exporters, exporter)
+		default:
+			fmt.Printf("unknown OTEL exporter type: %s", exp)
+		}
+	}
+
+	return exporters, nil
+}
+```
+
+The `newTracerProvider` initializes a new tracer provider using the provided exporters.
+
+```go
+func newTracerProvider(exporters []sdktrace.SpanExporter) *sdktrace.TracerProvider {
+	serviceName := os.Getenv("OTEL_SERVICE_NAME")
+	if serviceName == "" {
+		serviceName = "golang-middleware-function"
+	}
+
+	// Ensure default SDK resources and the required service name are set.
+	r, err := resource.Merge(
+		resource.Default(),
+		resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceName(serviceName),
+		),
+	)
+
+	if err != nil {
+		panic(err)
+	}
+
+	opts := []sdktrace.TracerProviderOption{
+		sdktrace.WithResource(r),
+	}
+
+	for _, exporter := range exporters {
+		processor := sdktrace.NewBatchSpanProcessor(exporter)
+		opts = append(opts, sdktrace.WithSpanProcessor(processor))
+	}
+
+	return sdktrace.NewTracerProvider(opts...)
+}
+```
+
+Use the modified template to create a new function.
+
+```sh
+faas-cli new echo --lang golang-middleware-otel
+```
+
+Use environment variables to configure the traces exporter for the function.
+
+```diff
+functions:
+  greet:
+    lang: python3-http-otel
+    handler: ./greet
+    image: greet:latest
++    environment:
++      OTEL_SERVICE_NAME: greet.${NAMESPACE:-openfaas-fn}
++      OTEL_TRACES_EXPORTER: console,otlp
++      OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-collector:4317}
+```
+
+- `OTEL_SERVICE_NAME` sets the name of the service associated with the telemetry and is used to identify telemetry for a specific function. It can be set to any value you want but we recommend using the clear function identifier `<fn-name>.<fn-namespace>`.
+- `OTEL_TRACES_EXPORTER` specifies which tracer exporter to use. In this example traces are exported to `console` (stdout) and with `otlp` to send traces to an endpoint that accepts OTLP via gRPC.
+- `OTEL_EXPORTER_OTLP_ENDPOINT` sets the endpoint where telemetry is exported to.
+
+### Creating custom traces in the function handler
+
+When using a modified OpenTelemetry template the global trace provider can be retrieved to add custom spans or additional instrumentation libraries in the function handler.
+
+Make sure the install the required packages:
+
+```sh
+go get "go.opentelemetry.io/otel" \
+	"go.opentelemetry.io/otel/trace"
+```
+
+Add custom spans in the function handler:
+
+```go
+package function
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"sync"
+
+	"go.opentelemetry.io/otel"
+)
+
+var tracer trace.Tracer
+var mu sync.Mutex
+
+func getTracer() trace.Tracer {
+	if tracer == nil {
+		mu.Lock()
+		tracer = otel.GetTracerProvider().Tracer("function")
+		mu.Unlock()
+	}
+
+	return tracer
+}
+
+
+func Handle(w http.ResponseWriter, r *http.Request) {
+	ctx, span := getTracer().Start(r.Context(), "function-span")
+	defer span.End()
+
+	var input []byte
+
+	if r.Body != nil {
+		defer r.Body.Close()
+
+		body, _ := io.ReadAll(r.Body)
+
+		input = body
+	}
+
+	w.WriteHeader(http.StatusOK)
+	w.Write([]byte(fmt.Sprintf("Body: %s", string(input))))
+}
+```
+
+The function `otel.GetTracerProvider()` can be used to get the registered trace provider and create a new named tracer for the function.
+
+To create new span with a tracer, you’ll need a handle on a `context.Context` instance. These will typically come from the request object and may already contain a parent span from an [instrumentation library](https://opentelemetry.io/docs/languages/go/libraries/).
+
+Checkout the [OpenTelemetry docs](https://opentelemetry.io/docs/languages/go/instrumentation/) for more information on how to work with spans.
+
+## OpenTelemetry zero-code instrumentation
+
+The beta Release for [zero-code instrumentation](https://opentelemetry.io/docs/concepts/instrumentation/zero-code/) of Go applications [has recently been announced](https://opentelemetry.io/blog/2025/go-auto-instrumentation-beta/).
+
+Go auto-instrumentation has not been tested with OpenFaaS functions yet. The easiest way to try it out on Kubernetes is probably by using the [Opentelemetry Operator for Kubernetes](https://opentelemetry.io/docs/platforms/kubernetes/operator/automatic/).

docs/languages/python.md

@@ -442,7 +442,7 @@ functions:
 +      OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-collector:4317}
 ```
 
-- `OTEL_SERVICE_NAME` sets the name of the service associated with the telemetry and is used to identify telemetry for a specific function. It can be set to any value you want be we recommend using the clear function identifier `<fn-name>.<fn-namespace>`.
+- `OTEL_SERVICE_NAME` sets the name of the service associated with the telemetry and is used to identify telemetry for a specific function. It can be set to any value you want but we recommend using the clear function identifier `<fn-name>.<fn-namespace>`.
 - `OTEL_TRACES_EXPORTER` specifies which tracer exporter to use. In this example traces are exported to `console` (stdout) and with `otlp`. The `otlp` option tells `opentelemetry-instrument` to send the traces to an endpoint that accepts OTLP via gRPC.
 - setting `OTEL_METRICS_EXPORTER` and `OTEL_LOGS_EXPORTER` to `none` we disable the metrics and logs exporters. You can enable them if desired.
 - `OTEL_EXPORTER_OTLP_ENDPOINT` sets the endpoint where telemetry is exported to.