Local Lambda tracing lifecycle example

Python:

pip install "opentelemetry-sdk==1.45.1" "opentelemetry-exporter-otlp-proto-http==1.45.1"

Go (OpenTelemetry Go v1.47 requires Go 1.26):

go get go.opentelemetry.io/otel@v1.47.0 go.opentelemetry.io/otel/sdk@v1.47.0 \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp@v1.47.0 \
  github.com/aws/aws-lambda-go@v1.55.1

If either key is missing the recipe does not crash and does not export: it logs one line (without echoing the environment) and the invocation returns your result. That is deliberate. Tracing must never fail the function.

Python (tracing.py, condensed; the file in the example also has the cold-start flag, the traceparent extraction and the flush budget):

# file: tracing.py
import os, threading, logging
from opentelemetry.exporter.otlp.proto.http import Compression
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

FLUSH_BUDGET_S, FLUSH_RESERVE_S = 2.0, 0.25   # example wait budget and safety reserve
log = logging.getLogger("lambda_tracing")

def build_provider():
    fn = os.environ.get("AWS_LAMBDA_FUNCTION_NAME")
    project = os.environ.get("FI_PROJECT_NAME") or fn or "aws-lambda"
    attrs = {"project_name": project, "project_type": "observe", "service.name": project}
    if fn:
        attrs["faas.name"] = fn            # only when the runtime provides it
    provider = TracerProvider(resource=Resource.create(attrs))
    key, secret = os.environ.get("FI_API_KEY"), os.environ.get("FI_SECRET_KEY")
    if key and secret:
        base = os.environ.get("FI_BASE_URL", "https://api.futureagi.com").rstrip("/")
        exporter = OTLPSpanExporter(
            endpoint=f"{base}/tracer/v1/traces",
            headers={"X-Api-Key": key, "X-Secret-Key": secret},
            timeout=int(FLUSH_BUDGET_S),
            compression=Compression.NoCompression,        # Compatible with older self-hosted receivers
        )
        # a long timer: the explicit flush below is what exports, never the timer
        provider.add_span_processor(BatchSpanProcessor(exporter, schedule_delay_millis=60_000))
    else:
        log.warning("FI_API_KEY / FI_SECRET_KEY not set: tracing is off, spans are not exported")
    return provider

def flush(provider, context):
    """Never raises, never waits longer than Lambda has left."""
    try:
        budget = min(FLUSH_BUDGET_S, context.get_remaining_time_in_millis() / 1000 - FLUSH_RESERVE_S)
        if budget <= 0:
            log.warning("flush skipped: not enough time left, spans of this invocation are lost")
            return
        # BatchSpanProcessor.force_flush can hold for the exporter timeout, so stop waiting at the budget
        t = threading.Thread(target=provider.force_flush, args=(int(budget * 1000),), daemon=True)
        t.start(); t.join(budget)
    except Exception as exc:
        log.warning("flush failed (%s), spans of this invocation are lost", type(exc).__name__)

# file: handler.py
from opentelemetry.trace import SpanKind, Status, StatusCode
import tracing

PROVIDER = tracing.build_provider()          # once per execution environment, outside the handler
TRACER = PROVIDER.get_tracer("lambda-handler")

def lambda_handler(event, context):
    try:
        with TRACER.start_as_current_span(
            "lambda.handler", kind=SpanKind.SERVER, attributes={"fi.span.kind": "CHAIN"},
            record_exception=False, set_status_on_exception=False,
        ) as span:
            try:
                return do_work(event)              # your code, your instrumentors
            except Exception as exc:
                span.set_status(Status(StatusCode.ERROR, type(exc).__name__))
                raise
    finally:
        tracing.flush(PROVIDER, context)           # the root span has ended; flush on success and on error

Go (tracing/tracing.go and handler/handler.go in the example; this is a condensed version):

var provider *sdktrace.TracerProvider // built once in main(), outside the handler

func Init() *sdktrace.TracerProvider {
	fn := os.Getenv("AWS_LAMBDA_FUNCTION_NAME")
	project := cmp.Or(os.Getenv("FI_PROJECT_NAME"), fn, "aws-lambda")
	attrs := []attribute.KeyValue{
		attribute.String("project_name", project), attribute.String("project_type", "observe"),
		attribute.String("service.name", project),
	}
	if fn != "" {
		attrs = append(attrs, attribute.String("faas.name", fn))
	}
	opts := []sdktrace.TracerProviderOption{sdktrace.WithResource(resource.NewSchemaless(attrs...))}
	if key, secret := os.Getenv("FI_API_KEY"), os.Getenv("FI_SECRET_KEY"); key != "" && secret != "" {
		base := cmp.Or(strings.TrimRight(os.Getenv("FI_BASE_URL"), "/"), "https://api.futureagi.com")
		exp, err := otlptracehttp.New(context.Background(),
			otlptracehttp.WithEndpointURL(base+"/tracer/v1/traces"),
			otlptracehttp.WithHeaders(map[string]string{"X-Api-Key": key, "X-Secret-Key": secret}),
			otlptracehttp.WithCompression(otlptracehttp.NoCompression), // Compatible with older self-hosted receivers
			otlptracehttp.WithTimeout(2*time.Second))
		if err == nil {
			opts = append(opts, sdktrace.WithBatcher(exp, sdktrace.WithBatchTimeout(time.Minute)))
		}
	} else {
		log.Print("FI_API_KEY / FI_SECRET_KEY not set: tracing is off, spans are not exported")
	}
	provider = sdktrace.NewTracerProvider(opts...)
	return provider
}

func Flush(ctx context.Context) {
	budget := 2 * time.Second
	if dl, ok := ctx.Deadline(); ok { // Lambda sets the invocation deadline on ctx
		budget = min(budget, time.Until(dl)-250*time.Millisecond)
	}
	if budget <= 0 {
		log.Print("flush skipped: not enough time left, spans of this invocation are lost")
		return
	}
	// a cancelled invocation context still gets its flush attempt, with the budget
	fctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), budget)
	defer cancel()
	if err := provider.ForceFlush(fctx); err != nil {
		log.Printf("flush did not complete (%T), spans of this invocation may be lost", err)
	}
}

func Handle(ctx context.Context, event json.RawMessage) (map[string]any, error) {
	defer Flush(ctx)          // runs after invoke has returned, so the root span has ended
	return invoke(ctx, event) // starts "lambda.handler" with tracer.Start, ends it with defer span.End()
}

The compiled cmd/function entry point uses lambda.Start(handler.Handle). The snippets explain the lifecycle; use the complete files linked above for the local example.