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.
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.Datasets Property¶
Gets the client for creating and populating Langfuse datasets (the eval cases experiment runs are scored against). Inert when this session is disabled.
Property Value¶
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.
Property Value¶
ILangfuseSession.ScoreConfigs Property¶
Gets the client for idempotently registering Langfuse score configs so eval scores render with defined data types, ranges, and category sets. Inert when this session is disabled.
Property Value¶
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.
Property Value¶
Methods¶
ILangfuseSession.AddTraceCommentAsync(string, string, CancellationToken) Method¶
Attaches a comment to an existing trace — for example a CI run URL, git commit, or a failing assertion message. No-op when this session is disabled.
System.Threading.Tasks.Task AddTraceCommentAsync(string traceId, string content, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
traceId System.String
The id of an existing Langfuse trace.
content System.String
The comment content (Langfuse limits this to 5000 characters).
cancellationToken System.Threading.CancellationToken
A cancellation token.
Returns¶
System.Threading.Tasks.Task
A task that completes once Langfuse has accepted the comment or the failure has been reported.
Remarks¶
Call this \<strong>after\</strong>Flush(Nullable<TimeSpan>) and after the trace has been ingested:
unlike scores, Langfuse rejects a comment whose target trace does not yet exist. Comment
failures are non-fatal and are reported through DiagnosticsCallback.
ILangfuseSession.BeginExperimentRun(string, string, string) Method¶
Begins a Langfuse experiment (dataset run). Each item begun on the returned run links its trace to the run so the recorded scores aggregate into the experiment-comparison view.
NexusLabs.Needlr.AgentFramework.Langfuse.ILangfuseExperimentRun BeginExperimentRun(string datasetName, string runName, string? runDescription=null);
Parameters¶
datasetName System.String
The dataset to score against. The dataset and its items must already exist — see Datasets.
runName System.String
A caller-supplied run name (for example a git SHA or CI run id) so runs are comparable.
runDescription System.String
An optional description applied to the run.
Returns¶
ILangfuseExperimentRun
An ILangfuseExperimentRun. When this session is disabled the run is inert.
Exceptions¶
System.ArgumentException
datasetName or runName is null or whitespace.
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.
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.