Skip to content

ILangfuseSession

NexusLabs.Needlr.AgentFramework.Langfuse

ILangfuseSession Interface

Represents an active Langfuse export session. Owns the OpenTelemetry tracer/meter providers that forward Needlr agent telemetry to Langfuse and flushes pending telemetry on disposal.

public interface ILangfuseSession : System.IDisposable

Implements System.IDisposable

Remarks

Obtain an instance from Start(LangfuseOptions). Keep it alive for the lifetime over which agent runs and evaluations should be captured (for example, an xUnit collection fixture), then dispose it to force a final flush.

Properties

ILangfuseSession.IsEnabled Property

Gets a value indicating whether this session is exporting telemetry. false when the supplied LangfuseOptions were not configured (for example, missing credentials), in which case the session is an inert no-op.

bool IsEnabled { get; }

Property Value

System.Boolean

ILangfuseSession.ScoresFailed Property

Gets the cumulative number of evaluation-score uploads that have failed across all scenarios created from this session. Always 0 under Strict (failures throw instead) and for a disabled session. Useful as an assertion target or a health indicator.

int ScoresFailed { get; }

Property Value

System.Int32

Methods

ILangfuseSession.BeginScenario(string, string, string, IEnumerable<string>, IReadOnlyDictionary<string,string>) Method

Begins a Langfuse trace scoped to a single eval scenario or agent run. Agent telemetry produced while the returned scenario is active nests under its trace, and evaluation scores can be attached to it.

NexusLabs.Needlr.AgentFramework.Langfuse.ILangfuseScenario BeginScenario(string name, string? sessionId=null, string? userId=null, System.Collections.Generic.IEnumerable<string>? tags=null, System.Collections.Generic.IReadOnlyDictionary<string,string>? metadata=null);

Parameters

name System.String

The trace name shown in Langfuse (for example the eval scenario name).

sessionId System.String

An optional Langfuse session id used to group related traces (for example multiple iterations of one scenario).

userId System.String

An optional end-user identifier associated with the trace.

tags System.Collections.Generic.IEnumerable<System.String>

Optional tags used to categorize the trace in Langfuse.

metadata System.Collections.Generic.IReadOnlyDictionary<System.String,System.String>

Optional filterable key/value metadata attached to the trace.

Returns

ILangfuseScenario
An ILangfuseScenario to dispose when the scenario completes. When this session is disabled the returned scenario is an inert no-op.

Exceptions

System.ArgumentException
name is null or whitespace.

ILangfuseSession.Flush(Nullable<TimeSpan>) Method

Flushes any buffered telemetry to Langfuse. Useful before reading results or at the end of a test run. No-op when IsEnabled is false.

bool Flush(System.Nullable<System.TimeSpan> timeout=null);

Parameters

timeout System.Nullable<System.TimeSpan>

Maximum time to wait for the flush to complete, or System.Threading.Timeout.InfiniteTimeSpan to wait indefinitely. When null, a provider default is used.

Returns

System.Boolean
true if the flush succeeded; otherwise false.