Crate cognis_trace 

Pluggable observability for Cognis.

Bridges cognis_core::CallbackHandler events to external observability backends. Phase 1 ships the bridge handler, three core types, two built-in exporters (stdout + mock), and the Langfuse backend (traces, prompts, scores). LangSmith and OpenTelemetry are Phase 2.

Quick start

use cognis_trace::{MockExporter, TraceMeta, TracingHandler};
use cognis_trace::meta::merge_into;

let handler = TracingHandler::builder()
    .with_exporter(MockExporter::new())
    .with_default_pricing()
    .build();

let metadata = merge_into(serde_json::Value::Null, TraceMeta::session("session-abc"));

See docs/superpowers/specs/2026-05-06-cognis-trace-design.md for the full design.

Re-exports

pub use batch::Batcher;

pub use batch::BatcherConfig;

pub use batch::BatcherStats;

pub use cost::default_pricing_2026_05;

pub use cost::ModelPrice;

pub use cost::PriceTable;

pub use error::TraceError;

pub use exporter::TraceExporter;

pub use exporters::mock::MockExporter;

pub use handler::TracingHandler;

pub use handler::TracingHandlerBuilder;

pub use meta::TraceMeta;

pub use prompts::ChatMessageTemplate;

pub use prompts::Prompt;

pub use prompts::PromptBody;

pub use prompts::PromptStore;

pub use scores::ScoreSink;

pub use span::CostDetails;

pub use span::Generation;

pub use span::ObservationLevel;

pub use span::ScoreRecord;

pub use span::ScoreValue;

pub use span::Span;

pub use span::SpanBuilder;

pub use span::SpanKind;

pub use span::TokenUsage;

pub use exporters::stdout::StdoutExporter;

Modules

batch

Batcher<T> — bounded queue + background flush task. Each exporter gets its own batcher so a slow backend doesn’t block the bridge.

cost

USD-cost computation. Per-million-token rates by model id.

error

Crate-wide error type. Exporter failures are never propagated into the user’s main code path — they are logged and counted. TraceError exists for diagnostic surfaces (stats(), builder validation).

exporter

TraceExporter trait — the contract for shipping spans to a backend.

exporters

Concrete exporter implementations.

handler

TracingHandler — CallbackHandler impl that translates lifecycle events into Spans and fans them out to per-exporter batchers.

meta

Well-known keys in RunnableConfig.metadata. The bridge handler reads these on the trace root to populate trace-level fields. Users construct them with the builder helpers below.

parent

Task-local span stack used as the fallback parent-id source when RunnableConfig.parent_run_id is None at a callback site. Composition sites that propagate parent_run_id explicitly bypass this stack.

prompts

PromptStore trait — pull versioned prompts from an external store. Concrete impls live alongside their backend (exporters/langfuse/prompts.rs).

scores

ScoreSink trait — submit evaluation scores to an external store.

span

Core span / generation / score types. Aligned with Langfuse’s observation model so the Langfuse exporter is a 1:1 mapping. See the spec, §4.