Skip to content

Feat: Lineage telemetry plugin — two facts-only spans per exchange #761

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JoshSag wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Feat: Lineage telemetry plugin — two facts-only spans per exchange #761

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cf3a922
Feat: Add the lineage-telemetry plugin
JoshSag Aug 14, 2026
d43523f
Feat: Register lineage-telemetry behind an exclude_plugin build tag
JoshSag Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions authbridge/authlib/go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ require (
github.com/open-policy-agent/opa v1.18.2
github.com/rossoctl/context-guru v0.0.0-20260720181432-8fc7c7b36563
github.com/spiffe/go-spiffe/v2 v2.8.1
go.opentelemetry.io/otel v1.44.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0
go.opentelemetry.io/otel/sdk v1.44.0
go.opentelemetry.io/otel/trace v1.44.0
golang.org/x/net v0.57.0
golang.org/x/sys v0.47.0
google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa
Expand Down Expand Up @@ -45,6 +49,7 @@ require (
github.com/bytedance/gopkg v0.1.3 // indirect
github.com/bytedance/sonic v1.15.1 // indirect
github.com/bytedance/sonic/loader v0.5.1 // indirect
github.com/cenkalti/backoff/v5 v5.0.3 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/cloudwego/base64x v0.1.6 // indirect
github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 // indirect
Expand All @@ -56,6 +61,7 @@ require (
github.com/go-logr/stdr v1.2.2 // indirect
github.com/goccy/go-json v0.10.6 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 // indirect
github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
github.com/huandu/go-clone v1.7.3 // indirect
github.com/huandu/go-sqlbuilder v1.41.0 // indirect
Expand Down Expand Up @@ -108,10 +114,9 @@ require (
github.com/yashtewari/glob-intersection v0.2.0 // indirect
github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/otel v1.44.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.44.0 // indirect
go.opentelemetry.io/otel/metric v1.44.0 // indirect
go.opentelemetry.io/otel/sdk v1.44.0 // indirect
go.opentelemetry.io/otel/trace v1.44.0 // indirect
go.opentelemetry.io/proto/otlp v1.10.0 // indirect
go.starlark.net v0.0.0-20260708150628-5395d018f003 // indirect
go.yaml.in/yaml/v2 v2.4.4 // indirect
go.yaml.in/yaml/v3 v3.0.4 // indirect
Expand All @@ -120,6 +125,7 @@ require (
golang.org/x/sync v0.22.0 // indirect
golang.org/x/text v0.40.0 // indirect
golang.org/x/time v0.15.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af // indirect
gopkg.in/ini.v1 v1.67.3 // indirect
oras.land/oras-go/v2 v2.6.2 // indirect
Expand Down
79 changes: 79 additions & 0 deletions authbridge/authlib/plugins/lineage/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
package lineage

import (
"bytes"
"encoding/json"
"fmt"
"strings"
)

// Config holds the per-plugin configuration decoded from the pipeline YAML.
type Config struct {
// OTelEndpoint is the OTLP gRPC endpoint (host:port or http://host:port).
// Default: "localhost:4317"
OTelEndpoint string `json:"otel_endpoint"`

// CaptureIO when true attaches parsed request/response content as
// input.value (request span) and output.value (response span)
// attributes, enabling Phoenix to display message content inline.
//
// For A2A (inbound agent calls): input = user message parts, output = artifact.
// For MCP tools/call: input = tool params JSON, output = tool result JSON.
// For Inference (LLM): input = messages array JSON, output = completion text.
//
// Off by default — enable only if traces do not contain PII or the
// OTel backend enforces appropriate access controls.
CaptureIO bool `json:"capture_io"`

// BypassPaths lists URL path prefixes that should not generate lineage
// hops. Useful for suppressing infrastructure polling (agent-card
// discovery, health checks) that would otherwise flood the lineage graph.
// Default: ["/.well-known/", "/healthz", "/readyz", "/health"]
BypassPaths []string `json:"bypass_paths"`

// BypassHosts lists target host substrings (matched against pctx.Host)
// that should not generate lineage hops. Useful for suppressing
// infrastructure outbound calls such as OTel trace exports.
// Default: ["otel-collector", "jaeger", "zipkin", "prometheus"]
BypassHosts []string `json:"bypass_hosts"`

// SelfID is the agent's own stable identifier, emitted as the
// lineage.self.id fact on every span. Typically the Keycloak client ID
// of this workload. If empty, SelfIDFile is consulted instead.
SelfID string `json:"self_id"`

// SelfIDFile is the path to a file containing the agent's own client ID.
// Defaults to /shared/client-id.txt (the operator-mounted credential).
// Ignored when SelfID is set.
SelfIDFile string `json:"self_id_file"`
}

func defaultConfig() Config {
return Config{
OTelEndpoint: "localhost:4317",
BypassPaths: []string{"/.well-known/", "/healthz", "/readyz", "/health"},
BypassHosts: []string{"otel-collector", "jaeger", "zipkin", "prometheus"},
SelfIDFile: "/shared/client-id.txt",
}
}

func decodeConfig(raw json.RawMessage) (Config, error) {
cfg := defaultConfig()
if len(raw) == 0 {
return cfg, nil
}
// Unknown keys are a boot error: a typo'd knob (capture-io, selfid_file)
// must not silently run with defaults.
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&cfg); err != nil {
return Config{}, fmt.Errorf("lineage-telemetry config: %w", err)
}
if cfg.OTelEndpoint == "" {
cfg.OTelEndpoint = "localhost:4317"
}
// Strip http:// or https:// prefix — gRPC NewClient expects host:port only.
cfg.OTelEndpoint = strings.TrimPrefix(cfg.OTelEndpoint, "https://")
cfg.OTelEndpoint = strings.TrimPrefix(cfg.OTelEndpoint, "http://")
return cfg, nil
}
Loading
Loading