Documentation
¶
Overview ¶
Package langfuse wires ADK Go telemetry to a Langfuse instance via OTLP/HTTP.
It is fully self-contained — it has zero imports from any host application. Any project using the ADK can import this package as a library, call Setup to configure the exporter and get back the plugin config and a shutdown function.
The plugin is safe for multi-agent flows: single agents, sequential delegation (transfer_to_agent), SequentialAgent, LoopAgent and ParallelAgent are all supported. Parallel branches are isolated via the ADK Branch() identifier so that concurrent sub-agents never mix their spans or LLM payloads.
Index ¶
- func EnvironmentFromContext(ctx context.Context) string
- func ReleaseFromContext(ctx context.Context) string
- func Setup(cfg *Config) (runner.PluginConfig, func(context.Context) error, error)
- func TagsFromContext(ctx context.Context) []string
- func TraceMetadataFromContext(ctx context.Context) map[string]string
- func TraceNameFromContext(ctx context.Context) string
- func UserIDFromContext(ctx context.Context) string
- func WithEnvironment(ctx context.Context, environment string) context.Context
- func WithRelease(ctx context.Context, release string) context.Context
- func WithTags(ctx context.Context, tags []string) context.Context
- func WithTraceMetadata(ctx context.Context, metadata map[string]string) context.Context
- func WithTraceName(ctx context.Context, name string) context.Context
- func WithUserID(ctx context.Context, userID string) context.Context
- type Config
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnvironmentFromContext ¶
EnvironmentFromContext returns the environment previously stored with WithEnvironment, or "" if none was set.
func ReleaseFromContext ¶
ReleaseFromContext returns the release previously stored with WithRelease, or "" if none was set.
func Setup ¶
Setup initialises the full Langfuse integration: an OTLP/HTTP trace exporter pointed at the Langfuse ingestion endpoint, an enriching span exporter that injects LLM request/response payloads, and an ADK plugin that captures them.
It returns a runner.PluginConfig ready to pass to the ADK launcher/runner and a shutdown function that flushes pending spans. The caller must defer the shutdown function.
Usage:
pluginCfg, shutdown, err := langfuse.Setup(&langfuse.Config{
PublicKey: os.Getenv("LANGFUSE_PUBLIC_KEY"),
SecretKey: os.Getenv("LANGFUSE_SECRET_KEY"),
Host: "https://cloud.langfuse.com",
})
if err != nil { log.Fatal(err) }
defer shutdown(context.Background())
runnr, _ := runner.New(runner.Config{
Agent: myAgent,
PluginConfig: pluginCfg,
})
func TagsFromContext ¶
TagsFromContext returns the tags previously stored with WithTags, or nil if none were set.
func TraceMetadataFromContext ¶
TraceMetadataFromContext returns the metadata map previously stored with WithTraceMetadata, or nil if none was set.
func TraceNameFromContext ¶
TraceNameFromContext returns the trace name previously stored with WithTraceName, or "" if none was set.
func UserIDFromContext ¶
UserIDFromContext returns the Langfuse user ID previously stored with WithUserID, or "" if none was set.
func WithEnvironment ¶
WithEnvironment stores the deployment environment name in the context. The spanEnricher reads it in beforeAgent and sets the langfuse.environment span attribute. This supplements the static Config.Environment value when the environment needs to vary per request.
func WithRelease ¶
WithRelease stores a release/version tag in the context. The spanEnricher reads it in beforeAgent and sets the langfuse.release span attribute. This supplements the static Config.Release value when the version needs to vary per request.
func WithTags ¶
WithTags stores a set of free-form tags in the context. The spanEnricher reads them in beforeAgent and sets the langfuse.trace.tags span attribute.
Tags appear in the Langfuse UI as filterable labels on the trace.
func WithTraceMetadata ¶
WithTraceMetadata stores arbitrary key-value metadata in the context. The spanEnricher reads the map in beforeAgent and sets one langfuse.trace.metadata.<key> span attribute per entry.
Multiple callers can cooperate by reading, copying, and extending the existing map — the context itself is immutable so no mutex is needed.
func WithTraceName ¶
WithTraceName stores an explicit trace name in the context. The spanEnricher reads it in beforeAgent and sets the langfuse.trace.name span attribute. When absent Langfuse auto-generates a name from the root span.
func WithUserID ¶
WithUserID stores a Langfuse user ID in the context. The spanEnricher reads it in beforeAgent and sets the langfuse.user.id span attribute. When absent the plugin falls back to the ADK-native ctx.UserID().
Typical caller: an HTTP middleware that extracts the authenticated user from the request (e.g. from a JWT).
Types ¶
type Config ¶
type Config struct {
// PublicKey is the Langfuse project public key used as the Basic Auth
// username for the OTLP ingestion endpoint.
PublicKey string `yaml:"publicKey" json:"publicKey"`
// SecretKey is the Langfuse project secret key used as the Basic Auth
// password for the OTLP ingestion endpoint.
SecretKey string `yaml:"secretKey" json:"secretKey"`
// Host is the base URL of the Langfuse server (e.g.
// "https://eu.cloud.langfuse.com"). When empty it defaults to the Langfuse
// Cloud US endpoint.
Host string `yaml:"host" json:"host"`
// Environment is an optional deployment environment tag forwarded to every
// trace (e.g. "production", "staging").
Environment string `yaml:"environment" json:"environment"`
// Release is an optional application version tag forwarded to every trace.
Release string `yaml:"release" json:"release"`
// ServiceName is the OpenTelemetry service.name resource attribute. Host
// applications should set this to their own name. Defaults to
// "langfuse-adk" when empty.
ServiceName string `yaml:"serviceName,omitempty" json:"serviceName,omitempty"`
// Insecure disables TLS for the OTLP/HTTP exporter. Set to true only when
// connecting to a self-hosted Langfuse instance that does not serve HTTPS
// (e.g. plain-HTTP local development). The default (false) keeps TLS
// enabled, which is required for the public Langfuse Cloud endpoints.
Insecure bool `yaml:"insecure,omitempty" json:"insecure,omitempty"`
}
Config holds the credentials and optional metadata needed to export traces to a Langfuse instance via OTLP/HTTP.
Host applications should embed or reference this struct directly (e.g. as a YAML field) rather than defining their own mirror type. Struct tags for yaml and json are provided so it can be unmarshalled from configuration files without any adapter code.
Source Files