cognis-trace

cognis-trace translates Cognis runtime events into spans, generations, and scores, then ships them to one or more exporters. Langfuse is the supported production backend; stdout and mock exporters ship for local use; OpenTelemetry support is on the roadmap.

Crate metadata

Field	Value
Latest version	`0.3`
docs.rs	docs.rs/cognis-trace
Repo path	`crates/cognis-trace`
Default features	`stdout`

Modules at a glance

Module	What
`handler`	`TracingHandler`, `TracingHandlerBuilder`. Implements `CallbackHandler`.
`exporter`	`TraceExporter` trait.
`exporters::stdout`	`StdoutExporter`, `StdoutExporter::compact()`.
`exporters::langfuse`	`LangfuseExporter`, `LangfuseConfig`, `LangfusePromptClient`, `LangfuseScorer`.
`cost`	`PriceTable`, `ModelPrice`.
`meta`	`TraceMeta::session/user/release/environment`, `merge_into`.
`span`	`Span`, `Generation`.
`parent`	Parent-span tracking via `parent_run_id`.
`prompts`	`Prompt`, `PromptStore`, `PromptBody`.
`scores`	`ScoreSink`, `ScoreRecord`, `ScoreValue`.
`batch`	`Batcher`, `BatcherConfig`.

Key types

TracingHandler

pub struct TracingHandler { /* … */ }

impl TracingHandler {
    pub fn builder() -> TracingHandlerBuilder;
    pub fn record_score(&self, score: ScoreRecord);
    pub fn stats(&self, exporter_name: &str) -> Option<(usize, usize, usize)>;
    pub async fn shutdown(self);
}

Implements CallbackHandler. Use as an Observer via cognis_core::HandlerObserver(handler).

TracingHandlerBuilder

Method	Purpose
`with_exporter<E: TraceExporter + 'static>(e: E)`	Append an exporter. Multiple are fine.
`with_default_pricing()`	Load the dated default price table.
`with_pricing(PriceTable)`	Custom price table.
`override_price(model, ModelPrice)`	Single-model override.
`with_batcher_config(BatcherConfig)`	Tune batching.
`build()`	`TracingHandler`. Spawns one batcher per exporter.

Exporters

// Stdout (always available; default feature):
let exp = StdoutExporter::compact();   // or StdoutExporter::default()

// Langfuse (feature `langfuse`):
let exp = LangfuseExporter::from_env()?;
let exp = LangfuseExporter::new(LangfuseConfig::from_env()?)?;

// Mock (testing):
let exp = MockExporter::new();

TraceExporter:

#[async_trait]
pub trait TraceExporter: Send + Sync {
    fn name(&self) -> &str;
    async fn export_spans(&self, spans: Vec<Span>) -> Result<(), TraceError>;
    async fn export_scores(&self, scores: Vec<ScoreRecord>) -> Result<(), TraceError>;
}

Implement for OTel or any other backend.

Cost

pub struct ModelPrice {
    pub input: f64,        // USD per 1M tokens
    pub output: f64,
    pub cache_read: f64,
    pub cache_write: f64,
}

pub struct PriceTable { /* … */ }

impl PriceTable {
    pub fn with_defaults() -> Self;
    pub fn insert(&mut self, model: impl Into<String>, price: ModelPrice);
}

TraceMeta

impl TraceMeta {
    pub fn session(id: impl Into<String>) -> (&'static str, Value);
    pub fn user(id: impl Into<String>) -> (&'static str, Value);
    pub fn release(s: impl Into<String>) -> (&'static str, Value);
    pub fn environment(s: impl Into<String>) -> (&'static str, Value);
}

pub fn merge_into(metadata: Value, kv: (&str, Value)) -> Value;

Langfuse prompt client

pub struct LangfusePromptClient { /* … */ }

impl LangfusePromptClient {
    pub fn new(cfg: LangfuseConfig) -> Result<Self, TraceError>;
    pub async fn get(&self, name: &str) -> Result<Prompt, TraceError>;
    pub async fn get_version(&self, name: &str, version: u32) -> Result<Prompt, TraceError>;
    pub async fn get_label(&self, name: &str, label: &str) -> Result<Prompt, TraceError>;
}

Scores

pub enum ScoreValue {
    Numeric(f64),
    Categorical(String),
    Boolean(bool),
}

pub struct ScoreRecord {
    pub run_id: Uuid,
    pub trace_id: Option<Uuid>,
    pub session_id: Option<String>,
    pub name: String,
    pub value: ScoreValue,
    pub comment: Option<String>,
}

#[async_trait]
pub trait ScoreSink: Send + Sync {
    async fn submit(&self, record: ScoreRecord) -> Result<(), TraceError>;
}

LangfuseScorer::new(LangfuseConfig::from_env()?)? is a built-in ScoreSink.

Feature flags

Feature	Pulls in
`stdout`	`StdoutExporter` (default).
`langfuse`	`reqwest`, `secrecy`, `base64`, plus the Langfuse exporter / prompt client / scorer.
`all`	Every exporter.
`integration_tests`	Tests that hit real services (off by default).

Trace with Langfuse

User guide.

Cost tracking

Pricing.

Prompts and scores

Versioned prompts and eval scores.

API per crate

Reference

Crate metadata

Modules at a glance

Key types

TracingHandler

TracingHandlerBuilder

Exporters

Cost

TraceMeta

Langfuse prompt client

Scores

Feature flags

See also

Trace with Langfuse

Cost tracking

Prompts and scores

​Crate metadata

​Modules at a glance

​Key types

​TracingHandler

​TracingHandlerBuilder

​Exporters

​Cost

​TraceMeta

​Langfuse prompt client

​Scores

​Feature flags

​See also

Trace with Langfuse

Cost tracking

Prompts and scores

Crate metadata

Modules at a glance

Key types

TracingHandler

TracingHandlerBuilder

Exporters

Cost

TraceMeta

Langfuse prompt client

Scores

Feature flags

See also