Skip to main content

Documentation Index

Fetch the complete documentation index at: https://cognis.vasanth.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldValue
Latest version0.3
docs.rsdocs.rs/cognis-trace
Repo pathcrates/cognis-trace
Default featuresstdout

​
Modules at a glance

ModuleWhat
handlerTracingHandler, TracingHandlerBuilder. Implements CallbackHandler.
exporterTraceExporter trait.
exporters::stdoutStdoutExporter, StdoutExporter::compact().
exporters::langfuseLangfuseExporter, LangfuseConfig, LangfusePromptClient, LangfuseScorer.
costPriceTable, ModelPrice.
metaTraceMeta::session/user/release/environment, merge_into.
spanSpan, Generation.
parentParent-span tracking via parent_run_id.
promptsPrompt, PromptStore, PromptBody.
scoresScoreSink, ScoreRecord, ScoreValue.
batchBatcher, 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

MethodPurpose
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

FeaturePulls in
stdoutStdoutExporter (default).
langfusereqwest, secrecy, base64, plus the Langfuse exporter / prompt client / scorer.
allEvery exporter.
integration_testsTests that hit real services (off by default).

​
See also

Trace with Langfuse

User guide.

Cost tracking

Pricing.

Prompts and scores

Versioned prompts and eval scores.