Skip to content

LangfuseOptions

NexusLabs.Needlr.AgentFramework.Langfuse

LangfuseOptions Class

Configuration for exporting Needlr agent telemetry and evaluation scores to Langfuse.

public sealed class LangfuseOptions

Inheritance System.Object 🡒 LangfuseOptions

Remarks

The common path is FromEnvironment(), which reads the standard Langfuse environment variables. When the public/secret keys are absent the integration disables itself and behaves as a no-op, so credential-less CI runs never fail.

Needlr emits OpenTelemetry traces and metrics under well-known source and meter names. The defaults here match NexusLabs.Needlr.AgentFramework.Diagnostics.AgentFrameworkMetricsOptions. If a consumer has customised those names via ConfigureMetrics(...), set AgentActivitySourceName, AgentMeterName, and GenAiMeterName to the same values, or add them through AdditionalActivitySources / AdditionalMeters.

Fields

LangfuseOptions.HostEnvironmentVariable Field

Environment variable read for the Langfuse host (base URL) by FromEnvironment().

public const string HostEnvironmentVariable = "LANGFUSE_HOST";

Field Value

System.String

LangfuseOptions.PublicKeyEnvironmentVariable Field

Environment variable read for the Langfuse public key by FromEnvironment().

public const string PublicKeyEnvironmentVariable = "LANGFUSE_PUBLIC_KEY";

Field Value

System.String

LangfuseOptions.SecretKeyEnvironmentVariable Field

Environment variable read for the Langfuse secret key by FromEnvironment().

public const string SecretKeyEnvironmentVariable = "LANGFUSE_SECRET_KEY";

Field Value

System.String

Properties

LangfuseOptions.AdditionalActivitySources Property

Gets a mutable list of additional System.Diagnostics.ActivitySource names to export — for example a host's own source or MAF's agent source.

public System.Collections.Generic.IList<string> AdditionalActivitySources { get; }

Property Value

System.Collections.Generic.IList<System.String>

LangfuseOptions.AdditionalMeters Property

Gets a mutable list of additional System.Diagnostics.Metrics.Meter names to export.

public System.Collections.Generic.IList<string> AdditionalMeters { get; }

Property Value

System.Collections.Generic.IList<System.String>

LangfuseOptions.AgentActivitySourceName Property

Gets or sets the name of Needlr's agent System.Diagnostics.ActivitySource to export. Defaults to NexusLabs.Needlr.AgentFramework.Diagnostics.AgentFrameworkMetricsOptions.MeterName's default.

public string AgentActivitySourceName { get; set; }

Property Value

System.String

LangfuseOptions.AgentMeterName Property

Gets or sets the name of Needlr's agent System.Diagnostics.Metrics.Meter to export. Defaults to NexusLabs.Needlr.AgentFramework.Diagnostics.AgentFrameworkMetricsOptions.MeterName's default.

public string AgentMeterName { get; set; }

Property Value

System.String

LangfuseOptions.DiagnosticsCallback Property

Gets or sets an optional callback for library diagnostic messages — for example, the warning emitted when credentials are present but no export target (Host or Region) was chosen. Wire it to your logger to surface these conditions.

public System.Action<string>? DiagnosticsCallback { get; set; }

Property Value

System.Action<System.String>

LangfuseOptions.Enabled Property

Gets or sets a value indicating whether export is enabled. When true (the default) export still only occurs if PublicKey and SecretKey are both present — see IsConfigured. Set to false to force a no-op regardless of credentials.

public bool Enabled { get; set; }

Property Value

System.Boolean

LangfuseOptions.Environment Property

Gets or sets the Langfuse deployment environment (for example ci, local, staging, or production). When set, it is emitted as langfuse.environment on every exported span so Langfuse partitions this run's data — keeping CI eval noise out of production dashboards. null by default (Langfuse uses its default environment).

public string? Environment { get; set; }

Property Value

System.String

LangfuseOptions.GenAiMeterName Property

Gets or sets the name of the meter that owns the gen_ai.client.token.usage histogram shared by Needlr and MEAI. Defaults to NexusLabs.Needlr.AgentFramework.Diagnostics.AgentFrameworkMetricsOptions.GenAiMeterName's default ("Experimental.Microsoft.Extensions.AI").

public string GenAiMeterName { get; set; }

Property Value

System.String

LangfuseOptions.HasCredentials Property

Gets a value indicating whether both API keys are present and export is enabled. Does not account for whether an export target was chosen — see HasExplicitTarget and IsConfigured.

public bool HasCredentials { get; }

Property Value

System.Boolean

LangfuseOptions.HasExplicitTarget Property

Gets a value indicating whether an explicit export target was chosen — either a Host (self-hosted) or a Region (deliberate Langfuse Cloud opt-in).

public bool HasExplicitTarget { get; }

Property Value

System.Boolean

LangfuseOptions.Host Property

Gets or sets the Langfuse base URL (for example https://cloud.langfuse.com or a self-hosted http://localhost:3000). When set, this takes precedence over Region. When null, the URL is derived from Region.

public string? Host { get; set; }

Property Value

System.String

LangfuseOptions.IncludeMetrics Property

Gets or sets a value indicating whether Needlr's gen_ai metrics (including the gen_ai.client.token.usage histogram) are exported alongside traces. Defaults to false.

public bool IncludeMetrics { get; set; }

Property Value

System.Boolean

Remarks

As of Langfuse v3.x the OTLP metrics endpoint (/api/public/otel/v1/metrics) accepts requests (returns HTTP 200) but does \<strong>not\</strong> ingest the data — there is no corresponding metrics read API, so exported metrics are silently discarded. Token usage is already carried on the generation spans, so metrics export is off by default. Enable this only if you point the exporter at a backend that ingests OTLP metrics.

LangfuseOptions.IsConfigured Property

Gets a value indicating whether the integration is fully configured to export: credentials are present, export is enabled, and an explicit target (Host or Region) was chosen. Requiring an explicit target prevents accidentally sending traces to Langfuse Cloud.

public bool IsConfigured { get; }

Property Value

System.Boolean

LangfuseOptions.NormalizeScoreNames Property

Gets or sets a value indicating whether evaluator metric names are normalised to snake_case before being sent as Langfuse score names. Off by default; names are sent verbatim. Enable for consistent dashboard filtering/grouping.

public bool NormalizeScoreNames { get; set; }

Property Value

System.Boolean

LangfuseOptions.PublicKey Property

Gets or sets the Langfuse public key (pk-lf-...). Required for export.

public string? PublicKey { get; set; }

Property Value

System.String

LangfuseOptions.Region Property

Gets or sets the Langfuse Cloud data region. null by default — exporting to a cloud region is therefore an explicit, opt-in choice. Ignored when Host is set.

public System.Nullable<NexusLabs.Needlr.AgentFramework.Langfuse.LangfuseRegion> Region { get; set; }

Property Value

System.Nullable<LangfuseRegion>

Remarks

To avoid silently sending traces (which may include prompts, agent outputs, and customer data) to Langfuse Cloud, this integration requires an \<strong>explicit\</strong> target: set Host for a self-hosted deployment, or set Region to deliberately opt in to a Langfuse Cloud region. When neither is set, export is disabled even if credentials are present (see IsConfigured) and a message is sent to DiagnosticsCallback.

LangfuseOptions.Release Property

Gets or sets the application release identifier (for example a git SHA or semantic version). When set, it is emitted as langfuse.release on every exported span so scores, cost, and latency can be compared across releases. null by default.

public string? Release { get; set; }

Property Value

System.String

LangfuseOptions.SamplingRatio Property

Gets or sets the head-based trace sampling ratio in the range 0.0 to 1.0. Defaults to 1.0 (sample everything), which is appropriate for eval workloads.

public double SamplingRatio { get; set; }

Property Value

System.Double

LangfuseOptions.ScoreErrorCallback Property

Gets or sets an optional callback invoked when a score upload fails under NonFatal. Use it to log the loss with your own logger.

public System.Action<NexusLabs.Needlr.AgentFramework.Langfuse.LangfuseScoreError>? ScoreErrorCallback { get; set; }

Property Value

System.Action<LangfuseScoreError>

LangfuseOptions.ScoreFailureMode Property

Gets or sets how a failed evaluation-score upload is handled. Defaults to NonFatal so a transient Langfuse outage does not turn a passing eval into a failure.

public NexusLabs.Needlr.AgentFramework.Langfuse.LangfuseScoreFailureMode ScoreFailureMode { get; set; }

Property Value

LangfuseScoreFailureMode

LangfuseOptions.SecretKey Property

Gets or sets the Langfuse secret key (sk-lf-...). Required for export.

public string? SecretKey { get; set; }

Property Value

System.String

LangfuseOptions.ServiceName Property

Gets or sets the OpenTelemetry service.name resource attribute applied to exported telemetry. Surfaces in Langfuse as the originating service. Defaults to "needlr-agent".

public string ServiceName { get; set; }

Property Value

System.String

LangfuseOptions.ServiceVersion Property

Gets or sets the optional OpenTelemetry service.version resource attribute.

public string? ServiceVersion { get; set; }

Property Value

System.String

Methods

LangfuseOptions.FromEnvironment() Method

Builds a LangfuseOptions from the standard Langfuse environment variables (PublicKeyEnvironmentVariable, SecretKeyEnvironmentVariable, and HostEnvironmentVariable).

public static NexusLabs.Needlr.AgentFramework.Langfuse.LangfuseOptions FromEnvironment();

Returns

LangfuseOptions
A populated LangfuseOptions. When the keys are absent the result has IsConfigured equal to false and the integration no-ops.