Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

refactor(observability): build langfuse spans from run observations

Steven Enamakelefe8ab23a759
diff --git a/crates/openhuman-core/src/core/observability/progress_tracing.rs b/crates/openhuman-core/src/core/observability/progress_tracing.rs
index 4f2d4081e0..4bff63f513 100644
--- a/crates/openhuman-core/src/core/observability/progress_tracing.rs
+++ b/crates/openhuman-core/src/core/observability/progress_tracing.rs
@@ -21,4 +21,3 @@ pub(crate) fn export_brand() -> ExportBrand<'static> {
#[cfg(test)]
pub(crate) use export::build_subagent_trace;
pub(crate) use export::{export_run_trace_from_journal, export_subagent_journal_trace};
-
diff --git a/crates/openhuman-core/src/flows/ops/langfuse_export.rs b/crates/openhuman-core/src/flows/ops/langfuse_export.rs
index a28e6c80fa..cf8044337f 100644
--- a/crates/openhuman-core/src/flows/ops/langfuse_export.rs
+++ b/crates/openhuman-core/src/flows/ops/langfuse_export.rs
@@ -6,10 +6,9 @@
//! OTLP proxy route (Langfuse v4; the legacy batch ingestion path is not used
//! for traces).
//!
-//! The trace is built by `tinyagents`' [`GraphLangfuseExporter`], which turns
-//! each superstep and node into a timed span and stamps the Langfuse **Agent
-//! Graph view** keys (`langgraph_node` / `langgraph_step`) on node spans, so
-//! the Langfuse UI can render the flow run as a graph, then projects it to
+//! The trace mapper turns TinyFlows run observations into timed generic
+//! harness spans, stamps the Langfuse **Agent Graph view** keys
+//! (`langgraph_node` / `langgraph_step`) on node spans, and projects them to
//! v4 OTLP: trace name, session, tags, release and flow metadata ride on every
//! span, since v4 filters observations directly. A host span-metadata
//! injector additionally stamps `flow_id` on every span for filtering.
@@ -26,13 +25,13 @@
use std::time::Duration;
-use std::collections::{BTreeMap, HashMap, VecDeque};
+use std::collections::{HashMap, VecDeque};
use serde_json::{json, Value};
use tinyagents_harness::observability::spans::{Span, SpanExporter, SpanState};
use tinyagents_harness::{LangfuseAuth, LangfuseClient, LangfuseTraceConfig};
-use tinyflows::graph::stream::GraphEvent;
use tinyflows::engine::GraphObservation;
+use tinyflows::graph::stream::GraphEvent;
use tinyflows_bus::runs::FlowRunTrigger;
use crate::config::Config;
@@ -125,7 +124,10 @@ fn flow_spans(flow_id: &str, observations: &[GraphObservation]) -> Vec<Span> {
let root_run_id = first.root_run_id.as_str();
let run_span_id = format!("{trace_id}:run:{root_run_id}");
let terminal = observations.iter().rev().find(|obs| {
- matches!(obs.event, GraphEvent::RunCompleted { .. } | GraphEvent::RunFailed { .. })
+ matches!(
+ obs.event,
+ GraphEvent::RunCompleted { .. } | GraphEvent::RunFailed { .. }
+ )
});
let mut run_span = Span::new(
run_span_id.clone(),
@@ -162,33 +164,79 @@ fn flow_spans(flow_id: &str, observations: &[GraphObservation]) -> Vec<Span> {
GraphEvent::StepCompleted { step } => {
if let Some(start) = pop_start(&mut step_starts, step) {
consumed[index] = true;
- output.push(step_span(flow_id, trace_id, &run_span_id, *step, observations, start, index));
+ output.push(step_span(
+ flow_id,
+ trace_id,
+ &run_span_id,
+ *step,
+ observations,
+ start,
+ index,
+ ));
}
}
GraphEvent::NodeStarted { node, step } => {
- node_starts.entry((node.as_str().to_owned(), *step)).or_default().push_back(index);
+ node_starts
+ .entry((node.as_str().to_owned(), *step))
+ .or_default()
+ .push_back(index);
consumed[index] = true;
}
GraphEvent::NodeCompleted { node, step } => {
- if let Some(start) = pop_start(&mut node_starts, &(node.as_str().to_owned(), *step)) {
+ if let Some(start) = pop_start(&mut node_starts, &(node.as_str().to_owned(), *step))
+ {
consumed[index] = true;
- output.push(node_span(flow_id, trace_id, node.as_str(), *step, observations, start, index, None));
+ output.push(node_span(
+ flow_id,
+ trace_id,
+ node.as_str(),
+ *step,
+ observations,
+ start,
+ index,
+ None,
+ ));
}
}
GraphEvent::NodeFailed { node, step, error } => {
- if let Some(start) = pop_start(&mut node_starts, &(node.as_str().to_owned(), *step)) {
+ if let Some(start) = pop_start(&mut node_starts, &(node.as_str().to_owned(), *step))
+ {
consumed[index] = true;
- output.push(node_span(flow_id, trace_id, node.as_str(), *step, observations, start, index, Some(error)));
+ output.push(node_span(
+ flow_id,
+ trace_id,
+ node.as_str(),
+ *step,
+ observations,
+ start,
+ index,
+ Some(error),
+ ));
}
}
GraphEvent::SubgraphStarted { node, namespace } => {
- subgraph_starts.entry((node.as_str().to_owned(), namespace.clone())).or_default().push_back(index);
+ subgraph_starts
+ .entry((node.as_str().to_owned(), namespace.clone()))
+ .or_default()
+ .push_back(index);
consumed[index] = true;
}
GraphEvent::SubgraphCompleted { node, namespace } => {
- if let Some(start) = pop_start(&mut subgraph_starts, &(node.as_str().to_owned(), namespace.clone())) {
+ if let Some(start) = pop_start(
+ &mut subgraph_starts,
+ &(node.as_str().to_owned(), namespace.clone()),
+ ) {
consumed[index] = true;
- output.push(subgraph_span(flow_id, trace_id, &run_span_id, node.as_str(), namespace, observations, start, index));
+ output.push(subgraph_span(
+ flow_id,
+ trace_id,
+ &run_span_id,
+ node.as_str(),
+ namespace,
+ observations,
+ start,
+ index,
+ ));
}
}
_ => {}
@@ -196,19 +244,45 @@ fn flow_spans(flow_id: &str, observations: &[GraphObservation]) -> Vec<Span> {
}
for (step, starts) in step_starts {
for start in starts {
- output.push(step_span(flow_id, trace_id, &run_span_id, step, observations, start, start));
+ output.push(step_span(
+ flow_id,
+ trace_id,
+ &run_span_id,
+ step,
+ observations,
+ start,
+ start,
+ ));
output.last_mut().expect("just pushed").end_ms = None;
}
}
for ((node, step), starts) in node_starts {
for start in starts {
- output.push(node_span(flow_id, trace_id, &node, step, observations, start, start, None));
+ output.push(node_span(
+ flow_id,
+ trace_id,
+ &node,
+ step,
+ observations,
+ start,
+ start,
+ None,
+ ));
output.last_mut().expect("just pushed").end_ms = None;
}
}
for ((node, namespace), starts) in subgraph_starts {
for start in starts {
- output.push(subgraph_span(flow_id, trace_id, &run_span_id, &node, &namespace, observations, start, start));
+ output.push(subgraph_span(
+ flow_id,
+ trace_id,
+ &run_span_id,
+ &node,
+ &namespace,
+ observations,
+ start,
+ start,
+ ));
output.last_mut().expect("just pushed").end_ms = None;
}
}
@@ -218,15 +292,26 @@ fn flow_spans(flow_id: &str, observations: &[GraphObservation]) -> Vec<Span> {
}
let failed = matches!(observation.event, GraphEvent::RunFailed { .. });
let error = match &observation.event {
- GraphEvent::RunFailed { error, .. } | GraphEvent::NodeFailed { error, .. } => Some(error.as_str()),
+ GraphEvent::RunFailed { error, .. } | GraphEvent::NodeFailed { error, .. } => {
+ Some(error.as_str())
+ }
_ => None,
};
- let mut span = Span::new(observation.event_id.as_str(), observation.run_id.as_str(), observation.event.kind(), observation.ts_ms)
- .with_root_run_id(observation.root_run_id.as_str())
- .with_parent(&run_span_id)
- .with_event_id(observation.event_id.as_str());
+ let mut span = Span::new(
+ observation.event_id.as_str(),
+ observation.run_id.as_str(),
+ observation.event.kind(),
+ observation.ts_ms,
+ )
+ .with_root_run_id(observation.root_run_id.as_str())
+ .with_parent(&run_span_id)
+ .with_event_id(observation.event_id.as_str());
span.kind = "event-create".to_owned();
- span.status = if failed { SpanState::Error } else { SpanState::Unset };
+ span.status = if failed {
+ SpanState::Error
+ } else {
+ SpanState::Unset
+ };
span.status_message = error.map(str::to_owned);
add_observation_metadata(&mut span, observation, flow_id);
output.push(span);
@@ -234,43 +319,104 @@ fn flow_spans(flow_id: &str, observations: &[GraphObservation]) -> Vec<Span> {
output
}
-fn pop_start<K: std::hash::Hash + Eq>(starts: &mut HashMap<K, VecDeque<usize>>, key: &K) -> Option<usize> {
+fn pop_start<K: std::hash::Hash + Eq>(
+ starts: &mut HashMap<K, VecDeque<usize>>,
+ key: &K,
+) -> Option<usize> {
let queue = starts.get_mut(key)?;
let start = queue.pop_front();
- if queue.is_empty() { starts.remove(key); }
+ if queue.is_empty() {
+ starts.remove(key);
+ }
start
}
fn add_observation_metadata(span: &mut Span, observation: &GraphObservation, flow_id: &str) {
span.metadata.insert("flow_id".into(), json!(flow_id));
- span.metadata.insert("graph_id".into(), json!(observation.graph_id.as_str()));
- span.metadata.insert("run_id".into(), json!(observation.run_id.as_str()));
- span.metadata.insert("root_run_id".into(), json!(observation.root_run_id.as_str()));
- span.metadata.insert("parent_run_id".into(), json!(observation.parent_run_id.as_ref().map(|id| id.as_str())));
- span.metadata.insert("checkpoint_id".into(), json!(observation.checkpoint_id.as_ref().map(|id| id.as_str())));
- span.metadata.insert("namespace".into(), json!(observation.namespace));
+ span.metadata
+ .insert("graph_id".into(), json!(observation.graph_id.as_str()));
+ span.metadata
+ .insert("run_id".into(), json!(observation.run_id.as_str()));
+ span.metadata.insert(
+ "root_run_id".into(),
+ json!(observation.root_run_id.as_str()),
+ );
+ span.metadata.insert(
+ "parent_run_id".into(),
+ json!(observation.parent_run_id.as_ref().map(|id| id.as_str())),
+ );
+ span.metadata.insert(
+ "checkpoint_id".into(),
+ json!(observation.checkpoint_id.as_ref().map(|id| id.as_str())),
+ );
+ span.metadata
+ .insert("namespace".into(), json!(observation.namespace));
span.metadata.insert("step".into(), json!(observation.step));
- span.metadata.insert("offset".into(), json!(observation.offset));
- span.metadata.insert("event".into(), json!(observation.event));
+ span.metadata
+ .insert("offset".into(), json!(observation.offset));
+ span.metadata
+ .insert("event".into(), json!(observation.event));
}
-fn step_span(flow_id: &str, trace_id: &str, run_span_id: &str, step: usize, observations: &[GraphObservation], start: usize, end: usize) -> Span {
+fn step_span(
+ flow_id: &str,
+ trace_id: &str,
+ run_span_id: &str,
+ step: usize,
+ observations: &[GraphObservation],
+ start: usize,
+ end: usize,
+) -> Span {
let first = &observations[start];
let last = &observations[end];
- let mut span = Span::new(format!("{trace_id}:step:{step}"), first.run_id.as_str(), format!("step {step}"), first.ts_ms)
- .with_root_run_id(first.root_run_id.as_str()).with_parent(run_span_id).with_event_id(last.event_id.as_str());
- if end != start { span = span.finish(last.ts_ms, SpanState::Ok); }
+ let mut span = Span::new(
+ format!("{trace_id}:step:{step}"),
+ first.run_id.as_str(),
+ format!("step {step}"),
+ first.ts_ms,
+ )
+ .with_root_run_id(first.root_run_id.as_str())
+ .with_parent(run_span_id)
+ .with_event_id(last.event_id.as_str());
+ if end != start {
+ span = span.finish(last.ts_ms, SpanState::Ok);
+ }
add_observation_metadata(&mut span, first, flow_id);
span.metadata.insert("langgraph_step".into(), json!(step));
span
}
-fn node_span(flow_id: &str, trace_id: &str, node: &str, step: usize, observations: &[GraphObservation], start: usize, end: usize, error: Option<&str>) -> Span {
+fn node_span(
+ flow_id: &str,
+ trace_id: &str,
+ node: &str,
+ step: usize,
+ observations: &[GraphObservation],
+ start: usize,
+ end: usize,
+ error: Option<&str>,
+) -> Span {
let first = &observations[start];
let last = &observations[end];
- let mut span = Span::new(format!("{trace_id}:node:{node}:{step}"), first.run_id.as_str(), node, first.ts_ms)
- .with_root_run_id(first.root_run_id.as_str()).with_parent(format!("{trace_id}:step:{step}")).with_event_id(last.event_id.as_str());
- if end != start { span = span.finish(last.ts_ms, if error.is_some() { SpanState::Error } else { SpanState::Ok }); }
+ let mut span = Span::new(
+ format!("{trace_id}:node:{node}:{step}"),
+ first.run_id.as_str(),
+ node,
+ first.ts_ms,
+ )
+ .with_root_run_id(first.root_run_id.as_str())
+ .with_parent(format!("{trace_id}:step:{step}"))
+ .with_event_id(last.event_id.as_str());
+ if end != start {
+ span = span.finish(
+ last.ts_ms,
+ if error.is_some() {
+ SpanState::Error
+ } else {
+ SpanState::Ok
+ },
+ );
+ }
span.status_message = error.map(str::to_owned);
add_observation_metadata(&mut span, last, flow_id);
span.metadata.insert("langgraph_node".into(), json!(node));
@@ -278,18 +424,46 @@ fn node_span(flow_id: &str, trace_id: &str, node: &str, step: usize, observation
span
}
-fn subgraph_span(flow_id: &str, trace_id: &str, run_span_id: &str, node: &str, namespace: &[String], observations: &[GraphObservation], start: usize, end: usize) -> Span {
+fn subgraph_span(
+ flow_id: &str,
+ trace_id: &str,
+ run_span_id: &str,
+ node: &str,
+ namespace: &[String],
+ observations: &[GraphObservation],
+ start: usize,
+ end: usize,
+) -> Span {
let first = &observations[start];
let last = &observations[end];
- let mut span = Span::new(format!("{trace_id}:subgraph:{}", namespace.join("/")), first.run_id.as_str(), format!("subgraph {node}"), first.ts_ms)
- .with_root_run_id(first.root_run_id.as_str()).with_parent(run_span_id).with_event_id(last.event_id.as_str());
- if end != start { span = span.finish(last.ts_ms, SpanState::Ok); }
+ let mut span = Span::new(
+ format!("{trace_id}:subgraph:{}", namespace.join("/")),
+ first.run_id.as_str(),
+ format!("subgraph {node}"),
+ first.ts_ms,
+ )
+ .with_root_run_id(first.root_run_id.as_str())
+ .with_parent(run_span_id)
+ .with_event_id(last.event_id.as_str());
+ if end != start {
+ span = span.finish(last.ts_ms, SpanState::Ok);
+ }
add_observation_metadata(&mut span, last, flow_id);
span
}
-fn flow_otlp_requests(exporter: &SpanExporter, trace: LangfuseTraceConfig, flow_id: &str, observations: &[GraphObservation]) -> tinyagents_harness::error::Result<Vec<Value>> {
- exporter.build_otlp_requests(trace, &flow_spans(flow_id, observations), "openhuman", "openhuman.graph")
+fn flow_otlp_requests(
+ exporter: &SpanExporter,
+ trace: LangfuseTraceConfig,
+ flow_id: &str,
+ observations: &[GraphObservation],
+) -> tinyagents_harness::error::Result<Vec<Value>> {
+ exporter.build_otlp_requests(
+ trace,
+ &flow_spans(flow_id, observations),
+ "openhuman",
+ "openhuman.graph",
+ )
}
/// Exports one settled flow run to Langfuse as a single trace. Best-effort:
diff --git a/crates/openhuman-core/src/flows/ops/langfuse_export_tests.rs b/crates/openhuman-core/src/flows/ops/langfuse_export_tests.rs
index bbef937324..ff30ab5e8e 100644
--- a/crates/openhuman-core/src/flows/ops/langfuse_export_tests.rs
+++ b/crates/openhuman-core/src/flows/ops/langfuse_export_tests.rs
@@ -128,7 +128,12 @@ fn otlp_flow_trace_puts_flow_attributes_on_every_span() {
"completed",
FlowRunTrigger::Rpc,
);
- let requests = flow_otlp_requests(&SpanExporter::new(client), trace, "flow-1", &sample_observations(thread_id))
+ let requests = flow_otlp_requests(
+ &SpanExporter::new(client),
+ trace,
+ "flow-1",
+ &sample_observations(thread_id),
+ )
.expect("otlp requests");
let resource = &requests[0]["resourceSpans"][0];
assert_eq!(
diff --git a/crates/openhuman-core/src/flows/runs_adapter/projection.rs b/crates/openhuman-core/src/flows/runs_adapter/projection.rs
index 4a7c81ef2a..468a97e45f 100644
--- a/crates/openhuman-core/src/flows/runs_adapter/projection.rs
+++ b/crates/openhuman-core/src/flows/runs_adapter/projection.rs
@@ -4,9 +4,9 @@ use std::collections::{HashSet, VecDeque};
use std::sync::{LazyLock, Mutex};
use serde_json::Value;
+use tinyflows::engine::GraphObservation;
use tinyflows_bus::runs::FlowRunTrigger;
use tinyflows_bus::runs::{self, RunEvent};
-use tinyflows::engine::GraphObservation;
use crate::core::events::DomainEvent;
use crate::flows::runs_adapter::session::RunSession;
diff --git a/crates/openhuman-core/src/flows/runs_adapter/session.rs b/crates/openhuman-core/src/flows/runs_adapter/session.rs
index d9da366b7c..6d60fbec38 100644
--- a/crates/openhuman-core/src/flows/runs_adapter/session.rs
+++ b/crates/openhuman-core/src/flows/runs_adapter/session.rs
@@ -4,10 +4,10 @@ use std::collections::HashMap;
use std::sync::{Arc, LazyLock, Mutex};
use std::time::Duration;
+use tinyflows::engine::GraphObservation;
use tinyflows_bus::catalog::Workflow as Flow;
use tinyflows_bus::runs::FlowRunTrigger;
use tinyflows_bus::runs::{self, RunEvent};
-use tinyflows::engine::GraphObservation;
use super::{projection, RunBindings};
use crate::config::Config;