snapshot of https://github.com/ory/keto.git (master, 2026-09-16; blobs > 131072B omitted)

2026-09-16 01:08:34 +05:00
commit 9456a4e922
2560 changed files with 120911 additions and 0 deletions
--- a/oryx/otelx/attribute.go
+++ b/oryx/otelx/attribute.go
@@ -0,0 +1,54 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"database/sql"
+	"fmt"
+
+	"go.opentelemetry.io/otel/attribute"
+)
+
+const nullString = "<null>"
+
+func StringAttrs(attrs map[string]string) []attribute.KeyValue {
+	s := make([]attribute.KeyValue, 0, len(attrs))
+	for k, v := range attrs {
+		s = append(s, attribute.String(k, v))
+	}
+	return s
+}
+
+func AutoInt[I int | int32 | int64](k string, v I) attribute.KeyValue {
+	// Internally, the OpenTelemetry SDK uses int64 for all integer values anyway.
+	return attribute.Int64(k, int64(v))
+}
+
+func Nullable[V any, VN *V | sql.Null[V], A func(string, V) attribute.KeyValue](a A, k string, v VN) attribute.KeyValue {
+	switch v := any(v).(type) {
+	case *V:
+		if v == nil {
+			return attribute.String(k, nullString)
+		}
+		return a(k, *v)
+	case sql.Null[V]:
+		if !v.Valid {
+			return attribute.String(k, nullString)
+		}
+		return a(k, v.V)
+	}
+	// This should never happen, as the type switch above is exhaustive to the generic type VN.
+	return attribute.String(k, fmt.Sprintf("<got unsupported type %T>", v))
+}
+
+func NullString[V *string | sql.Null[string]](k string, v V) attribute.KeyValue {
+	return Nullable(attribute.String, k, v)
+}
+
+func NullStringer(k string, v fmt.Stringer) attribute.KeyValue {
+	if v == nil {
+		return attribute.String(k, nullString)
+	}
+	return attribute.String(k, v.String())
+}
--- a/oryx/otelx/config.go
+++ b/oryx/otelx/config.go
@@ -0,0 +1,67 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"bytes"
+	_ "embed"
+	"io"
+)
+
+type JaegerConfig struct {
+	LocalAgentAddress string         `json:"local_agent_address"`
+	Sampling          JaegerSampling `json:"sampling"`
+}
+
+type ZipkinConfig struct {
+	ServerURL string         `json:"server_url"`
+	Sampling  ZipkinSampling `json:"sampling"`
+}
+
+type OTLPConfig struct {
+	ServerURL           string       `json:"server_url"`
+	Insecure            bool         `json:"insecure"`
+	Sampling            OTLPSampling `json:"sampling"`
+	AuthorizationHeader string       `json:"authorization_header"`
+}
+
+type JaegerSampling struct {
+	ServerURL    string  `json:"server_url"`
+	TraceIDRatio float64 `json:"trace_id_ratio"`
+}
+
+type ZipkinSampling struct {
+	SamplingRatio float64 `json:"sampling_ratio"`
+}
+
+type OTLPSampling struct {
+	SamplingRatio float64 `json:"sampling_ratio"`
+}
+
+type ProvidersConfig struct {
+	Jaeger JaegerConfig `json:"jaeger"`
+	Zipkin ZipkinConfig `json:"zipkin"`
+	OTLP   OTLPConfig   `json:"otlp"`
+}
+
+type Config struct {
+	ServiceName           string          `json:"service_name"`
+	DeploymentEnvironment string          `json:"deployment_environment"`
+	Provider              string          `json:"provider"`
+	Providers             ProvidersConfig `json:"providers"`
+}
+
+//go:embed config.schema.json
+var ConfigSchema []byte
+
+const ConfigSchemaID = "ory://tracing-config"
+
+// AddConfigSchema adds the tracing schema to the compiler.
+// The interface is specified instead of `jsonschema.Compiler` to allow the use of any jsonschema library fork or version.
+func AddConfigSchema(c interface {
+	AddResource(url string, r io.Reader) error
+},
+) error {
+	return c.AddResource(ConfigSchemaID, bytes.NewReader(ConfigSchema))
+}
--- a/oryx/otelx/config.schema.json
+++ b/oryx/otelx/config.schema.json
@@ -0,0 +1,152 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ory://tracing-config",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Configure distributed tracing using OpenTelemetry",
+  "properties": {
+    "provider": {
+      "type": "string",
+      "description": "Set this to the tracing backend you wish to use. Supports Jaeger, Zipkin, and OTEL.",
+      "enum": ["jaeger", "otel", "zipkin"],
+      "examples": ["jaeger"]
+    },
+    "service_name": {
+      "type": "string",
+      "description": "Specifies the service name to use on the tracer.",
+      "examples": ["Ory Hydra", "Ory Kratos", "Ory Keto", "Ory Oathkeeper"]
+    },
+    "deployment_environment": {
+      "type": "string",
+      "description": "Specifies the deployment environment to use on the tracer.",
+      "examples": ["development", "staging", "production"]
+    },
+    "providers": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "jaeger": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Configures the jaeger tracing backend.",
+          "properties": {
+            "local_agent_address": {
+              "type": "string",
+              "description": "The address of the jaeger-agent where spans should be sent to.",
+              "anyOf": [
+                {
+                  "title": "IPv6 Address and Port",
+                  "pattern": "^\\[(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))\\]:([0-9]*)$"
+                },
+                {
+                  "title": "IPv4 Address and Port",
+                  "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}:([0-9]*)$"
+                },
+                {
+                  "title": "Hostname and Port",
+                  "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9]):([0-9]*)$"
+                }
+              ],
+              "examples": ["127.0.0.1:6831"]
+            },
+            "sampling": {
+              "type": "object",
+              "propertyNames": {
+                "enum": ["server_url", "trace_id_ratio"]
+              },
+              "additionalProperties": false,
+              "properties": {
+                "server_url": {
+                  "type": "string",
+                  "description": "The address of jaeger-agent's HTTP sampling server",
+                  "format": "uri",
+                  "examples": ["http://localhost:5778/sampling"]
+                },
+                "trace_id_ratio": {
+                  "type": "number",
+                  "description": "Trace Id ratio sample",
+                  "examples": [0.5]
+                }
+              }
+            }
+          }
+        },
+        "zipkin": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Configures the zipkin tracing backend.",
+          "properties": {
+            "server_url": {
+              "type": "string",
+              "description": "The address of the Zipkin server where spans should be sent to.",
+              "format": "uri",
+              "examples": ["http://localhost:9411/api/v2/spans"]
+            },
+            "sampling": {
+              "type": "object",
+              "propertyNames": {
+                "enum": ["sampling_ratio"]
+              },
+              "additionalProperties": false,
+              "properties": {
+                "sampling_ratio": {
+                  "type": "number",
+                  "description": "Sampling ratio for spans.",
+                  "examples": [0.4]
+                }
+              }
+            }
+          }
+        },
+        "otlp": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Configures the OTLP tracing backend.",
+          "properties": {
+            "server_url": {
+              "type": "string",
+              "description": "The endpoint of the OTLP exporter (HTTP) where spans should be sent to.",
+              "anyOf": [
+                {
+                  "title": "IPv6 Address and Port",
+                  "pattern": "^\\[(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))\\]:([0-9]*)$"
+                },
+                {
+                  "title": "IPv4 Address and Port",
+                  "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}:([0-9]*)$"
+                },
+                {
+                  "title": "Hostname and Port",
+                  "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9]):([0-9]*)$"
+                }
+              ],
+              "examples": ["localhost:4318"]
+            },
+            "insecure": {
+              "type": "boolean",
+              "description": "Will use HTTP if set to true; defaults to HTTPS."
+            },
+            "sampling": {
+              "type": "object",
+              "propertyNames": {
+                "enum": ["sampling_ratio"]
+              },
+              "additionalProperties": false,
+              "properties": {
+                "sampling_ratio": {
+                  "type": "number",
+                  "description": "Sampling ratio for spans.",
+                  "examples": [0.4]
+                }
+              }
+            },
+            "authorization_header": {
+              "type": "string",
+              "examples": ["Bearer 2389s8fs9d8fus9f"]
+            }
+          }
+        }
+      }
+    }
+  }
+}
--- a/oryx/otelx/jaeger.go
+++ b/oryx/otelx/jaeger.go
@@ -0,0 +1,88 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"net"
+
+	"go.opentelemetry.io/contrib/propagators/b3"
+	jaegerPropagator "go.opentelemetry.io/contrib/propagators/jaeger"
+	"go.opentelemetry.io/contrib/samplers/jaegerremote"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/exporters/jaeger"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.27.0"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// SetupJaeger configures and returns a Jaeger tracer.
+//
+// The returned tracer will by default attempt to send spans to a local Jaeger agent.
+// Optionally, [otelx.JaegerConfig.LocalAgentAddress] can be set to specify a different target.
+//
+// By default, unless a parent sampler has taken a sampling decision, every span is sampled.
+// [otelx.JaegerSampling.TraceIDRatio] may be used to customize the sampling probability,
+// optionally alongside [otelx.JaegerSampling.ServerURL] to consult a remote server
+// for the sampling strategy to be used.
+func SetupJaeger(t *Tracer, tracerName string, c *Config) (trace.Tracer, error) {
+	host, port, err := net.SplitHostPort(c.Providers.Jaeger.LocalAgentAddress)
+	if err != nil {
+		return nil, err
+	}
+
+	exp, err := jaeger.New(
+		jaeger.WithAgentEndpoint(
+			jaeger.WithAgentHost(host), jaeger.WithAgentPort(port),
+		),
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	tpOpts := []sdktrace.TracerProviderOption{
+		sdktrace.WithBatcher(exp),
+		sdktrace.WithResource(resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceName(c.ServiceName),
+			semconv.DeploymentEnvironmentName(c.DeploymentEnvironment))),
+	}
+
+	samplingServerURL := c.Providers.Jaeger.Sampling.ServerURL
+	traceIdRatio := c.Providers.Jaeger.Sampling.TraceIDRatio
+
+	sampler := sdktrace.TraceIDRatioBased(traceIdRatio)
+
+	if samplingServerURL != "" {
+		sampler = jaegerremote.New(
+			"jaegerremote",
+			jaegerremote.WithSamplingServerURL(samplingServerURL),
+			jaegerremote.WithInitialSampler(sampler),
+		)
+	}
+
+	// Respect any sampling decision taken by the client.
+	sampler = sdktrace.ParentBased(sampler)
+	tpOpts = append(tpOpts, sdktrace.WithSampler(sampler))
+
+	tp := sdktrace.NewTracerProvider(tpOpts...)
+	otel.SetTracerProvider(tp)
+
+	// At the moment, software across our cloud stack only support Zipkin (B3)
+	// and Jaeger propagation formats. Proposals for standardized formats for
+	// context propagation are in the works (ref: https://www.w3.org/TR/trace-context/
+	// and https://www.w3.org/TR/baggage/).
+	//
+	// Simply add propagation.TraceContext{} and propagation.Baggage{}
+	// here to enable those as well.
+	prop := propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{},
+		jaegerPropagator.Jaeger{},
+		b3.New(b3.WithInjectEncoding(b3.B3MultipleHeader|b3.B3SingleHeader)),
+		propagation.Baggage{},
+	)
+	otel.SetTextMapPropagator(prop)
+	return tp.Tracer(tracerName), nil
+}
--- a/oryx/otelx/middleware.go
+++ b/oryx/otelx/middleware.go
@@ -0,0 +1,39 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"cmp"
+	"net/http"
+	"strings"
+
+	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+
+	"github.com/ory/x/httprouterx"
+)
+
+var withDefaultFilters = otelhttp.WithFilter(func(r *http.Request) bool {
+	return !(strings.HasPrefix(r.URL.Path, "/health") ||
+		strings.HasPrefix(r.URL.Path, "/admin/health") ||
+		strings.HasPrefix(r.URL.Path, "/metrics") ||
+		strings.HasPrefix(r.URL.Path, "/admin/metrics"))
+})
+
+func NewMiddleware(next http.Handler, operation string, opts ...otelhttp.Option) http.Handler {
+	myOpts := []otelhttp.Option{
+		withDefaultFilters,
+		otelhttp.WithSpanNameFormatter(func(operation string, r *http.Request) string {
+			return cmp.Or(r.Pattern, operation, r.Method+" "+r.URL.Path)
+		}),
+	}
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		callback := func(r2 *http.Request) {
+			r.Pattern = cmp.Or(r.Pattern, r2.Pattern)
+		}
+		r2 := httprouterx.WithAfterMatchHook(r, callback)
+		next.ServeHTTP(w, r2)
+		r.Pattern = cmp.Or(r2.Pattern, r.Pattern) // best-effort in case callback never is called
+	})
+	return otelhttp.NewHandler(handler, operation, append(myOpts, opts...)...)
+}
--- a/oryx/otelx/otel.go
+++ b/oryx/otelx/otel.go
@@ -0,0 +1,122 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/trace"
+	"go.opentelemetry.io/otel/trace/embedded"
+	"go.opentelemetry.io/otel/trace/noop"
+
+	"github.com/ory/x/logrusx"
+	"github.com/ory/x/stringsx"
+)
+
+type (
+	Tracer struct {
+		tracer trace.Tracer
+	}
+	Provider interface {
+		Tracer(ctx context.Context) *Tracer
+	}
+)
+
+// New creates a new tracer. If name is empty, a default tracer name is used
+// instead. See: https://godocs.io/go.opentelemetry.io/otel/sdk/trace#TracerProvider.Tracer
+func New(name string, l *logrusx.Logger, c *Config) (*Tracer, error) {
+	t := &Tracer{}
+
+	if err := t.setup(name, l, c); err != nil {
+		return nil, err
+	}
+
+	return t, nil
+}
+
+// NewNoop creates a new no-op tracer.
+func NewNoop() *Tracer {
+	tp := noop.NewTracerProvider()
+	t := &Tracer{tracer: tp.Tracer("")}
+	return t
+}
+
+type simpleProvider struct{ t *Tracer }
+
+func (p simpleProvider) Tracer(_ context.Context) *Tracer { return p.t }
+
+func NewNoopProvider() Provider { return &simpleProvider{t: NewNoop()} }
+
+// setup constructs the tracer based on the given configuration.
+func (t *Tracer) setup(name string, l *logrusx.Logger, c *Config) error {
+	switch f := stringsx.SwitchExact(c.Provider); {
+	case f.AddCase("jaeger"):
+		tracer, err := SetupJaeger(t, name, c)
+		if err != nil {
+			return err
+		}
+
+		t.tracer = tracer
+		l.Infof("Jaeger tracer configured! Sending spans to %s", c.Providers.Jaeger.LocalAgentAddress)
+	case f.AddCase("zipkin"):
+		tracer, err := SetupZipkin(t, name, c)
+		if err != nil {
+			return err
+		}
+
+		t.tracer = tracer
+		l.Infof("Zipkin tracer configured! Sending spans to %s", c.Providers.Zipkin.ServerURL)
+	case f.AddCase("otel"):
+		tracer, err := SetupOTLP(t, name, c)
+		if err != nil {
+			return err
+		}
+
+		t.tracer = tracer
+		l.Infof("OTLP tracer configured! Sending spans to %s", c.Providers.OTLP.ServerURL)
+	case f.AddCase(""):
+		l.Infof("No tracer configured - skipping tracing setup")
+		t.tracer = noop.NewTracerProvider().Tracer(name)
+	default:
+		return f.ToUnknownCaseErr()
+	}
+
+	return nil
+}
+
+// IsLoaded returns true if the tracer has been loaded.
+func (t *Tracer) IsLoaded() bool {
+	if t == nil || t.tracer == nil {
+		return false
+	}
+	return true
+}
+
+// Tracer returns the underlying OpenTelemetry tracer.
+func (t *Tracer) Tracer() trace.Tracer {
+	return t.tracer
+}
+
+// WithOTLP returns a new tracer with the underlying OpenTelemetry Tracer
+// replaced.
+func (t *Tracer) WithOTLP(other trace.Tracer) *Tracer {
+	return &Tracer{other}
+}
+
+// Provider returns a TracerProvider which in turn yields this tracer unmodified.
+func (t *Tracer) Provider() trace.TracerProvider {
+	return tracerProvider{t: t.Tracer()}
+}
+
+type tracerProvider struct {
+	embedded.TracerProvider
+	t trace.Tracer
+}
+
+var _ trace.TracerProvider = tracerProvider{}
+
+// Tracer implements trace.TracerProvider.
+func (tp tracerProvider) Tracer(name string, options ...trace.TracerOption) trace.Tracer {
+	return tp.t
+}
--- a/oryx/otelx/otlp.go
+++ b/oryx/otelx/otlp.go
@@ -0,0 +1,68 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"context"
+
+	"go.opentelemetry.io/contrib/propagators/b3"
+	jaegerPropagator "go.opentelemetry.io/contrib/propagators/jaeger"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.27.0"
+	"go.opentelemetry.io/otel/trace"
+)
+
+func SetupOTLP(t *Tracer, tracerName string, c *Config) (trace.Tracer, error) {
+	ctx := context.Background()
+
+	clientOpts := []otlptracehttp.Option{
+		otlptracehttp.WithEndpoint(c.Providers.OTLP.ServerURL),
+	}
+
+	if c.Providers.OTLP.Insecure {
+		clientOpts = append(clientOpts, otlptracehttp.WithInsecure())
+	}
+
+	if c.Providers.OTLP.AuthorizationHeader != "" {
+		clientOpts = append(clientOpts,
+			otlptracehttp.WithHeaders(map[string]string{"Authorization": c.Providers.OTLP.AuthorizationHeader}),
+		)
+	}
+
+	exp, err := otlptrace.New(
+		ctx, otlptracehttp.NewClient(clientOpts...),
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	tpOpts := []sdktrace.TracerProviderOption{
+		sdktrace.WithBatcher(exp),
+		sdktrace.WithResource(resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceName(c.ServiceName),
+			semconv.DeploymentEnvironmentName(c.DeploymentEnvironment),
+		)),
+		sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(
+			c.Providers.OTLP.Sampling.SamplingRatio,
+		))),
+	}
+
+	tp := sdktrace.NewTracerProvider(tpOpts...)
+	otel.SetTracerProvider(tp)
+
+	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{},
+		jaegerPropagator.Jaeger{},
+		b3.New(b3.WithInjectEncoding(b3.B3MultipleHeader|b3.B3SingleHeader)),
+		propagation.Baggage{},
+	))
+
+	return tp.Tracer(tracerName), nil
+}
--- a/oryx/otelx/semconv/context.go
+++ b/oryx/otelx/semconv/context.go
@@ -0,0 +1,53 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package semconv
+
+import (
+	"context"
+	"net/http"
+
+	"go.opentelemetry.io/otel/attribute"
+
+	"github.com/ory/x/httpx"
+)
+
+type contextKey int
+
+const contextKeyAttributes contextKey = iota
+
+func ContextWithAttributes(ctx context.Context, attrs ...attribute.KeyValue) context.Context {
+	existing, _ := ctx.Value(contextKeyAttributes).([]attribute.KeyValue)
+	return context.WithValue(ctx, contextKeyAttributes, append(existing, attrs...))
+}
+
+func AttributesFromContext(ctx context.Context) []attribute.KeyValue {
+	fromCtx, _ := ctx.Value(contextKeyAttributes).([]attribute.KeyValue)
+	uniq := make(map[attribute.Key]struct{})
+	attrs := make([]attribute.KeyValue, 0)
+	for i := len(fromCtx) - 1; i >= 0; i-- {
+		if _, ok := uniq[fromCtx[i].Key]; !ok {
+			uniq[fromCtx[i].Key] = struct{}{}
+			attrs = append(attrs, fromCtx[i])
+		}
+	}
+	reverse(attrs)
+	return attrs
+}
+
+func Middleware(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
+	ctx := ContextWithAttributes(r.Context(),
+		append(
+			AttrGeoLocation(*httpx.ClientGeoLocation(r)),
+			AttrClientIP(httpx.ClientIP(r)),
+		)...,
+	)
+
+	next(rw, r.WithContext(ctx))
+}
+
+func reverse[S ~[]E, E any](s S) {
+	for i, j := 0, len(s)-1; i < j; i, j = i+1, j-1 {
+		s[i], s[j] = s[j], s[i]
+	}
+}
--- a/oryx/otelx/semconv/deprecated.go
+++ b/oryx/otelx/semconv/deprecated.go
@@ -0,0 +1,38 @@
+// Copyright © 2024 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package semconv
+
+import (
+	"context"
+
+	otelattr "go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// NewDeprecatedFeatureUsedEvent creates a new event indicating that a deprecated feature was used.
+// It returns the event name and a trace.EventOption that can be used to
+// add the event to a span.
+//
+//	span.AddEvent(NewDeprecatedFeatureUsedEvent(ctx, "deprecated-feature-id", otelattr.String("key", "value")))
+func NewDeprecatedFeatureUsedEvent(ctx context.Context, deprecatedCodeFeatureID string, attrs ...otelattr.KeyValue) (string, trace.EventOption) {
+	return DeprecatedFeatureUsed.String(),
+		trace.WithAttributes(
+			append(
+				append(
+					attrs,
+					AttributesFromContext(ctx)...,
+				),
+				AttrDeprecatedFeatureID(deprecatedCodeFeatureID),
+			)...,
+		)
+}
+
+const (
+	AttributeKeyDeprecatedCodePathIDAttributeKey AttributeKey = "DeprecatedFeatureID"
+	DeprecatedFeatureUsed                        Event        = "DeprecatedFeatureUsed"
+)
+
+func AttrDeprecatedFeatureID(id string) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyDeprecatedCodePathIDAttributeKey.String(), id)
+}
--- a/oryx/otelx/semconv/events.go
+++ b/oryx/otelx/semconv/events.go
@@ -0,0 +1,104 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+// Package semconv contains OpenTelemetry semantic convention constants.
+package semconv
+
+import (
+	"github.com/gofrs/uuid"
+	otelattr "go.opentelemetry.io/otel/attribute"
+
+	"github.com/ory/x/httpx"
+)
+
+type Event string
+
+func (e Event) String() string {
+	return string(e)
+}
+
+type AttributeKey string
+
+func (a AttributeKey) String() string {
+	return string(a)
+}
+
+const (
+	AttributeKeyIdentityID           AttributeKey = "IdentityID"
+	AttributeKeyNID                  AttributeKey = "ProjectID"
+	AttributeKeyClientIP             AttributeKey = "ClientIP"
+	AttributeKeyGeoLocationCity      AttributeKey = "GeoLocationCity"
+	AttributeKeyGeoLocationRegion    AttributeKey = "GeoLocationRegion"
+	AttributeKeyGeoLocationCountry   AttributeKey = "GeoLocationCountry"
+	AttributeKeyGeoLocationLatitude  AttributeKey = "GeoLocationLatitude"
+	AttributeKeyGeoLocationLongitude AttributeKey = "GeoLocationLongitude"
+	AttributeKeyWorkspace            AttributeKey = "WorkspaceID"
+	AttributeKeySubscriptionID       AttributeKey = "SubscriptionID"
+	AttributeKeyProjectEnvironment   AttributeKey = "ProjectEnvironment"
+	AttributeKeyWorkspaceAPIKeyID    AttributeKey = "WorkspaceAPIKeyID"
+	AttributeKeyProjectAPIKeyID      AttributeKey = "ProjectAPIKeyID"
+)
+
+func AttrIdentityID[V string | uuid.UUID](val V) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyIdentityID.String(), uuidOrString(val))
+}
+
+func AttrNID(val uuid.UUID) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyNID.String(), val.String())
+}
+
+func AttrWorkspace(val uuid.UUID) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyWorkspace.String(), val.String())
+}
+
+func AttrSubscription(val uuid.UUID) otelattr.KeyValue {
+	return otelattr.String(AttributeKeySubscriptionID.String(), val.String())
+}
+
+func AttrProjectEnvironment(val string) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyProjectEnvironment.String(), val)
+}
+
+func AttrClientIP(val string) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyClientIP.String(), val)
+}
+
+func AttrGeoLocation(val httpx.GeoLocation) []otelattr.KeyValue {
+	geoLocationAttributes := make([]otelattr.KeyValue, 0, 3)
+
+	if val.City != "" {
+		geoLocationAttributes = append(geoLocationAttributes, otelattr.String(AttributeKeyGeoLocationCity.String(), val.City))
+	}
+	if val.Country != "" {
+		geoLocationAttributes = append(geoLocationAttributes, otelattr.String(AttributeKeyGeoLocationCountry.String(), val.Country))
+	}
+	if val.Region != "" {
+		geoLocationAttributes = append(geoLocationAttributes, otelattr.String(AttributeKeyGeoLocationRegion.String(), val.Region))
+	}
+	if val.Latitude != nil {
+		geoLocationAttributes = append(geoLocationAttributes, otelattr.Float64(AttributeKeyGeoLocationLatitude.String(), *val.Latitude))
+	}
+	if val.Longitude != nil {
+		geoLocationAttributes = append(geoLocationAttributes, otelattr.Float64(AttributeKeyGeoLocationLongitude.String(), *val.Longitude))
+	}
+
+	return geoLocationAttributes
+}
+
+func AttrWorkspaceAPIKeyID[V string | uuid.UUID](val V) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyWorkspaceAPIKeyID.String(), uuidOrString(val))
+}
+
+func AttrProjectAPIKeyID[V string | uuid.UUID](val V) otelattr.KeyValue {
+	return otelattr.String(AttributeKeyProjectAPIKeyID.String(), uuidOrString(val))
+}
+
+func uuidOrString[V string | uuid.UUID](val V) string {
+	switch val := any(val).(type) {
+	case string:
+		return val
+	case uuid.UUID:
+		return val.String()
+	}
+	panic("unreachable")
+}
--- a/oryx/otelx/semconv/warning.go
+++ b/oryx/otelx/semconv/warning.go
@@ -0,0 +1,38 @@
+// Copyright © 2024 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package semconv
+
+import (
+	"context"
+
+	otelattr "go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// NewWarning creates a new warning event with the given ID and attributes.
+// It returns the event name and a trace.EventOption that can be used to
+// add the event to a span.
+//
+//	span.AddEvent(NewWarning(ctx, "warning-id", otelattr.String("key", "value")))
+func NewWarning(ctx context.Context, id string, attrs ...otelattr.KeyValue) (string, trace.EventOption) {
+	return Warning.String(),
+		trace.WithAttributes(
+			append(
+				append(
+					attrs,
+					AttributesFromContext(ctx)...,
+				),
+				otelattr.String(AttributeWarningID.String(), id),
+			)...,
+		)
+}
+
+const (
+	Warning            Event        = "Warning"
+	AttributeWarningID AttributeKey = "WarningID"
+)
+
+func AttrWarningID(id string) otelattr.KeyValue {
+	return otelattr.String(AttributeWarningID.String(), id)
+}
--- a/oryx/otelx/withspan.go
+++ b/oryx/otelx/withspan.go
@@ -0,0 +1,148 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"reflect"
+	"runtime"
+	"strings"
+
+	pkgerrors "github.com/pkg/errors"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	semconv "go.opentelemetry.io/otel/semconv/v1.27.0"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// WithSpan wraps execution of f in a span identified by name.
+//
+// If f returns an error or panics, the span status will be set to the error
+// state. The error (or panic) will be propagated unmodified.
+//
+// f will be wrapped in a child span by default. To make a new root span
+// instead, pass the trace.WithNewRoot() option.
+func WithSpan(ctx context.Context, name string, f func(context.Context) error, opts ...trace.SpanStartOption) (err error) {
+	ctx, span := trace.SpanFromContext(ctx).TracerProvider().Tracer("").Start(ctx, name, opts...)
+	defer func() {
+		defer span.End()
+		if r := recover(); r != nil {
+			setErrorStatusPanic(span, r)
+			panic(r)
+		} else if err != nil {
+			span.SetStatus(codes.Error, err.Error())
+			setErrorTags(span, err)
+		}
+	}()
+	return f(ctx)
+}
+
+// End finishes span, and automatically sets the error state if *err is not nil
+// or during panicking.
+//
+// Usage:
+//
+//	func Divide(ctx context.Context, numerator, denominator int) (ratio int, err error) {
+//		ctx, span := tracer.Start(ctx, "Divide")
+//		defer otelx.End(span, &err)
+//		if denominator == 0 {
+//			return 0, errors.New("cannot divide by zero")
+//		}
+//		return numerator / denominator, nil
+//	}
+//
+// During a panic, we don't fully conform to OpenTelemetry's semantic
+// conventions because that would require us to emit a span event to attach the
+// stacktrace and error type, and we don't want to do that. Instead, we set the
+// tags on the span directly.
+// https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/
+//
+// For improved compatibility with Datadog, we also set some additional tags as
+// documented here:
+// https://docs.datadoghq.com/standard-attributes/?product=apm&search=error
+func End(span trace.Span, err *error) {
+	defer span.End()
+	if r := recover(); r != nil {
+		setErrorStatusPanic(span, r)
+		panic(r)
+	}
+	if err == nil || *err == nil {
+		return
+	}
+	span.SetStatus(codes.Error, (*err).Error())
+	setErrorTags(span, *err)
+}
+
+func setErrorStatusPanic(span trace.Span, recovered any) {
+	span.SetAttributes(
+		// OpenTelemetry says to add these attributes to an event, not the span
+		// itself. We don't want to do that, so we're adding them to the span
+		// directly.
+		semconv.ExceptionEscaped(true),
+		// OpenTelemetry describes "exception.stacktrace"  We don't love that,
+		// though, so we're using "error.stack" instead, like DataDog).
+		attribute.String("error.stack", stacktrace()),
+	)
+	if t := reflect.TypeOf(recovered); t != nil {
+		span.SetAttributes(semconv.ExceptionType(t.String()))
+	}
+	switch e := recovered.(type) {
+	case error:
+		span.SetStatus(codes.Error, "panic: "+e.Error())
+		setErrorTags(span, e)
+	case string, fmt.Stringer:
+		span.SetStatus(codes.Error, fmt.Sprintf("panic: %v", e))
+	default:
+		span.SetStatus(codes.Error, "panic")
+	case nil:
+		// nothing
+	}
+}
+
+func setErrorTags(span trace.Span, err error) {
+	span.SetAttributes(
+		attribute.String("error", err.Error()),
+		attribute.String("error.message", err.Error()),                        // DataDog compat
+		attribute.String("error.type", fmt.Sprintf("%T", errors.Unwrap(err))), // the innermost error type is the most useful here
+	)
+	if e := interface{ StackTrace() pkgerrors.StackTrace }(nil); errors.As(err, &e) {
+		span.SetAttributes(attribute.String("error.stack", fmt.Sprintf("%+v", e.StackTrace())))
+	}
+	if e := interface{ Reason() string }(nil); errors.As(err, &e) {
+		span.SetAttributes(attribute.String("error.reason", e.Reason()))
+	}
+	if e := interface{ Debug() string }(nil); errors.As(err, &e) {
+		span.SetAttributes(attribute.String("error.debug", e.Debug()))
+	}
+	if e := interface{ ID() string }(nil); errors.As(err, &e) {
+		span.SetAttributes(attribute.String("error.id", e.ID()))
+	}
+	if e := interface{ Details() map[string]interface{} }(nil); errors.As(err, &e) {
+		for k, v := range e.Details() {
+			span.SetAttributes(attribute.String("error.details."+k, fmt.Sprintf("%v", v)))
+		}
+	}
+}
+
+func stacktrace() string {
+	pc := make([]uintptr, 5)
+	n := runtime.Callers(4, pc)
+	if n == 0 {
+		return ""
+	}
+	pc = pc[:n]
+	frames := runtime.CallersFrames(pc)
+
+	var builder strings.Builder
+	for {
+		frame, more := frames.Next()
+		fmt.Fprintf(&builder, "%s\n\t%s:%d\n", frame.Function, frame.File, frame.Line)
+		if !more {
+			break
+		}
+	}
+	return builder.String()
+}
--- a/oryx/otelx/zipkin.go
+++ b/oryx/otelx/zipkin.go
@@ -0,0 +1,37 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package otelx
+
+import (
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/exporters/zipkin"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.27.0"
+	"go.opentelemetry.io/otel/trace"
+)
+
+func SetupZipkin(t *Tracer, tracerName string, c *Config) (trace.Tracer, error) {
+	exp, err := zipkin.New(c.Providers.Zipkin.ServerURL)
+	if err != nil {
+		return nil, err
+	}
+
+	tpOpts := []sdktrace.TracerProviderOption{
+		sdktrace.WithBatcher(exp),
+		sdktrace.WithResource(resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceName(c.ServiceName),
+			semconv.DeploymentEnvironmentName(c.DeploymentEnvironment),
+		)),
+		sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(
+			c.Providers.Zipkin.Sampling.SamplingRatio,
+		))),
+	}
+
+	tp := sdktrace.NewTracerProvider(tpOpts...)
+	otel.SetTracerProvider(tp)
+
+	return tp.Tracer(tracerName), nil
+}