ObservabilityBroadcaster¶
This docs was updated at: 2026-02-23
com.paragon.broadcasting.ObservabilityBroadcaster ยท Interface
Core abstraction for LLM observability and distributed tracing. Broadcasts telemetry data (traces, spans, metrics) to observability backends while maintaining semantic compliance with OpenTelemetry and GenAI conventions.
Focuses exclusively on observability: traces, observations, cost tracking, context propagation, and metadata management.
Methods¶
startTrace¶
Starts a new trace (root observation representing a complete interaction). Maps to OpenTelemetry root span.
Parameters
| Name | Description |
|---|---|
name |
The name of the trace |
traceContext |
The initial context (user, session, metadata, etc.) |
Returns
A trace handle to pass to observations
getTrace¶
Retrieves an existing trace by ID.
endTrace¶
Ends an active trace with the final output and status.
startObservation¶
Observation startObservation(
@NonNull String traceId,
@NonNull String name,
@NonNull ObservationType type,
@NonNull ObservationContext observationContext)
Starts a new observation (span) within a trace.
Parameters
| Name | Description |
|---|---|
traceId |
The parent trace ID |
name |
The name of the observation |
type |
The observation type (span, generation, event) |
observationContext |
The observation-specific context |
Returns
An observation handle
startObservation¶
Observation startObservation(
@NonNull String traceId,
@NonNull String parentObservationId,
@NonNull String name,
@NonNull ObservationType type,
@NonNull ObservationContext observationContext)
Starts a nested observation under a parent observation. Allows hierarchical span structures for agent graphs.
endObservation¶
Ends an active observation.
getObservation¶
Retrieves an existing observation by ID.
setAttribute¶
Sets attributes (key-value pairs) on an observation. Used for OpenTelemetry semantic convention attributes. Examples: gen_ai.system, gen_ai.request.model, gen_ai.usage.*, etc.
setAttributes¶
Sets multiple attributes at once.
setMetadata¶
Sets observation-level metadata (unstructured, searchable data). Nested keys are flattened for filtering (use langfuse.observation.metadata.* prefix).
setMetadataKey¶
Sets a single metadata key-value pair.
setTraceMetadata¶
Sets trace-level metadata (propagated across all observations if using baggage).
setTraceMetadataKey¶
Sets a single trace metadata key-value pair.
setInput¶
Sets the input for an observation. For generations: maps to gen_ai.prompt, input.value, mlflow.spanInputs
setOutput¶
Sets the output for an observation. For generations: maps to gen_ai.completion, output.value, mlflow.spanOutputs
setInputAndOutput¶
void setInputAndOutput(
@NonNull String observationId, @Nullable Object input, @Nullable Object output)
Sets both input and output at once (useful when completing an observation).
setModel¶
Sets the model name for a generation observation. Only applies to observations of type GENERATION.
Maps to: gen_ai.request.model, gen_ai.response.model, llm.model_name, model
setModelParameters¶
Sets model parameters (e.g., temperature, max_tokens, top_p). Only applies to observations of type GENERATION.
Maps to: gen_ai.request., llm.invocation_parameters.
setTokenUsage¶
Records token usage for a generation (input, output, total). Only applies to observations of type GENERATION.
Maps to: gen_ai.usage., llm.token_count.
setCost¶
Records the calculated cost of a generation in USD. Only applies to observations of type GENERATION.
Maps to: gen_ai.usage.cost, langfuse.observation.cost_details
setCompletionStartTime¶
Sets the completion start time (ISO 8601) for a generation. Useful for tracking token streaming delays. Only applies to observations of type GENERATION.
propagateContextAttributes¶
Sets trace-level baggage attributes that should propagate to ALL observations in the trace.
Propagated attributes: - userId (langfuse.user.id, user.id) - sessionId (langfuse.session.id, session.id) - release (langfuse.release) - version (langfuse.version) - environment (langfuse.environment) - tags (langfuse.trace.tags) - metadata (langfuse.trace.metadata.*)
Use OpenTelemetry Baggage + BaggageSpanProcessor for automatic propagation. This method is a convenience for manual propagation.
setTraceVersion¶
Sets the version of the trace (e.g., "1.0.0", "v2"). Useful for tracking application logic changes.
setTraceRelease¶
Sets the release identifier for the trace (e.g., "prod-2024-11-26"). Useful for deployment tracking.
setTraceEnvironment¶
Sets the deployment environment for the trace (e.g., "production", "staging", "development").
setObservationVersion¶
Sets the version for an observation (can differ from trace version).
setObservationEnvironment¶
Sets the environment for an observation (can differ from trace environment). Maps to: langfuse.environment, deployment.environment, deployment.environment.name
setTraceUserId¶
Sets the user ID for a trace (for per-user analytics and support). Should be propagated to all observations via baggage.
Maps to: langfuse.user.id, user.id
setTraceSessionId¶
Sets the session ID for a trace (for multi-turn conversations/workflows). Should be propagated to all observations via baggage.
Maps to: langfuse.session.id, session.id
addTraceTags¶
Adds tags to a trace for categorization and filtering. Example: ["production", "priority-high", "retry"]
removeTraceTag¶
Removes a tag from a trace.
setTraceTags¶
Sets all tags for a trace (replaces existing tags).
setObservationLevel¶
Sets the severity level of an observation.
Levels: DEBUG, DEFAULT, WARNING, ERROR Inferred from OpenTelemetry span.status.code if not explicitly set.
setObservationStatusMessage¶
Sets a status message for an observation (e.g., error message, reason for failure). Inferred from OpenTelemetry span.status.message if not explicitly set.
setObservationSuccess¶
Marks an observation as successful.
setObservationError¶
Marks an observation as failed with an optional error message.
logMultiModalInput¶
Logs multi-modal input (text, images, audio, etc.) for an observation.
Example: text prompt, screenshot, audio file, etc.
logMultiModalOutput¶
Logs multi-modal output for an observation.
Example: generated text, image, audio, etc.
logMultiModalInputItem¶
Logs a single multi-modal content item as input.
logMultiModalOutputItem¶
Logs a single multi-modal content item as output.
addTraceComment¶
Adds a comment/annotation to a trace. Useful for manual notes during debugging or analysis.
addObservationComment¶
void addObservationComment(
@NonNull String observationId, @NonNull String comment, @Nullable String author)
Adds a comment/annotation to an observation.
maskObservationInput¶
Masks (redacts) sensitive data in an observation's input. Useful for PII, API keys, passwords, etc.
maskObservationOutput¶
Masks (redacts) sensitive data in an observation's output.
setTracePublic¶
Marks a trace as public (allows sharing via URL).
getTraceMetrics¶
Retrieves aggregated metrics for a trace (cost, latency, token counts, etc.).
getTraceObservations¶
Retrieves all observations within a trace (for building agent graphs).
flush¶
Flushes any pending/buffered traces to the backend. Called automatically at shutdown but can be invoked manually for batch operations.
shutdown¶
Gracefully shuts down the provider, flushing all pending traces.