Expose tags in the collector. Allow passing tags via baml function baml_options (#2528)

# Pull Request Template

Thanks for taking the time to fill out this pull request!

## Issue Reference
Please link to any related issues
- [ ] This PR fixes/closes #[issue number]

## Changes
Please describe the changes proposed in this pull request

This PR surfaces span/function call tags via the `Collector`'s
`FunctionLog` across multiple language clients. This allows users to
retrieve tags, including those inherited from parent `@trace` contexts,
directly from the `FunctionLog` object.

Specifically:
- The Rust core `FunctionLog` now exposes a `tags()` method (an alias
for `metadata()`).
- This `tags` accessor is exposed in the Python, TypeScript, and Ruby
language clients.
- Integration tests have been added for Python and TypeScript to verify
that tags set in a parent `@trace` context are correctly propagated and
visible in the child function's `FunctionLog.tags`.

## Testing
Please describe how you tested these changes

- [x] Unit tests added/updated (Rust core)
- [x] Manual testing performed (Python and TypeScript integration tests)
- [ ] Tested in [environment]

The Rust core changes were verified with `cargo test -p baml-runtime
--lib`.
New Python integration test
`test_functionlog_tags_inherit_from_parent_trace` was run and passed.
New TypeScript integration test `"should include parent trace tags in
FunctionLog.tags"` was added and compiles; it will run in CI.

## Screenshots
If applicable, add screenshots to help explain your changes

[Add screenshots here...]

## PR Checklist
Please ensure you've completed these items

- [ ] I have read and followed the contributing guidelines
- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings

## Additional Notes
Add any other context about the PR here

The Go client was mentioned in the original task, but no explicit `tags`
accessor was added to its `FunctionLog` as part of these changes. The
existing `metadata` accessor in Go would provide similar functionality
if `tags` is an alias for `metadata`. The TypeScript integration test
compiles against the updated `native.d.ts` and runtime wrapper
implementation; it will run in CI once the workspace’s TS dependencies
are fully available.

---
<a
href="https://cursor.com/background-agent?bcId=bc-83c0460d-95c0-4ce7-afd0-bee8c222af3a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-cursor-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-cursor-light.svg"><img alt="Open in
Cursor"
src="https://cursor.com/open-in-cursor.svg"></picture></a>&nbsp;<a
href="https://cursor.com/agents?id=bc-83c0460d-95c0-4ce7-afd0-bee8c222af3a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-web-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-web-light.svg"><img alt="Open in Web"
src="https://cursor.com/open-in-web.svg"></picture></a>

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Add `tags` to TS sync client call options and pass them to runtime,
with tests ensuring FunctionLog includes parent trace and per-call tags.
> 
> - **TypeScript Client**:
> - Add `tags?: Record<string, string>` to `BamlCallOptions` in
`sync_client.ts` and forward `options.tags || {}` to all
`runtime.callFunctionSync` calls.
> - **Tracing/Tests**:
> - Update tests to set parent trace tags and assert they appear in
`FunctionLog.tags`.
> - Add test to pass per-call tags and verify both parent and
function-specific tags are preserved.
> - **Generated Code**:
> - Large auto-formatted changes in generated TypeScript request code
(no functional deltas highlighted).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
73cef16. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Cursor Agent <[email protected]>

Author: aaronvg

engine/baml-runtime/src/async_vm_runtime.rs

@@ -147,6 +147,7 @@ impl BamlAsyncVmRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         cancel_tripwire: Arc<TripWire>,
     ) -> (anyhow::Result<FunctionResult>, FunctionCallId) {
         // Find the function.
@@ -172,6 +173,7 @@ impl BamlAsyncVmRuntime {
                     tb,
                     cb,
                     collectors,
+                    tags,
                     env_vars,
                     cancel_tripwire,
                 )
@@ -181,7 +183,15 @@ impl BamlAsyncVmRuntime {
             .llm_runtime
             .tracer_wrapper
             .get_or_create_tracer(&env_vars)
-            .start_call(&function_name, ctx, params, true, false, collectors.clone())
+            .start_call(
+                &function_name,
+                ctx,
+                params,
+                true,
+                false,
+                collectors.clone(),
+                None,
+            )
             .curr_call_id();
 
         let Some(expr_fn) = self
@@ -246,6 +256,7 @@ impl BamlAsyncVmRuntime {
             (anyhow::Result<FunctionResult>, FunctionCallId),
         )>();
 
+        let tags_clone = tags.clone();
         let vm_result = 'mainloop: loop {
             match vm.exec() {
                 Ok(VmExecState::Await(idx)) => {
@@ -372,6 +383,7 @@ impl BamlAsyncVmRuntime {
                                 // TODO: Collectors are not supported yet.
                                 // let collectors = collectors.clone();
                                 let env_vars = env_vars.clone();
+                                let tags_for_future = tags_clone.clone();
 
                                 let futures_tx = futures_tx.clone();
 
@@ -388,6 +400,7 @@ impl BamlAsyncVmRuntime {
                                             tb.as_ref(),
                                             cb.as_ref(),
                                             None,
+                                            tags_for_future,
                                             env_vars,
                                             cancel_tripwire,
                                         )
@@ -646,6 +659,7 @@ impl BamlAsyncVmRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         cancel_tripwire: Arc<TripWire>,
     ) -> (anyhow::Result<FunctionResult>, FunctionCallId) {
         self.async_runtime.block_on(self.call_function(
@@ -656,6 +670,7 @@ impl BamlAsyncVmRuntime {
             cb,
             collectors,
             env_vars,
+            tags,
             cancel_tripwire,
         ))
     }
@@ -669,6 +684,7 @@ impl BamlAsyncVmRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         // FunctionResultStream is responsible for freeing the TripWire and the clean up.
         cancel_tripwire: Arc<TripWire>,
     ) -> anyhow::Result<FunctionResultStream> {
@@ -680,6 +696,7 @@ impl BamlAsyncVmRuntime {
             cb,
             collectors,
             env_vars,
+            tags,
             cancel_tripwire,
         )
     }

engine/baml-runtime/src/cli/repl.rs

@@ -527,6 +527,7 @@ impl ReplState {
                                 None,
                                 None,
                                 None,
+                                None, // tags
                                 env_vars,
                                 TripWire::new_with_on_drop(
                                     None,

engine/baml-runtime/src/cli/serve/mod.rs

@@ -357,6 +357,7 @@ Streaming is available via http://localhost:{port}/stream/{{FunctionName}}, but
                 None,
                 client_registry.as_ref(),
                 None,
+                None, // tags
                 env_vars,
                 TripWire::new(None),
             )
@@ -460,6 +461,7 @@ Streaming is available via http://localhost:{port}/stream/{{FunctionName}}, but
                 client_registry.as_ref(),
                 Some(vec![]),
                 env_vars,
+                None, // tags
                 TripWire::new(None),
             );
 

engine/baml-runtime/src/eval_expr.rs

@@ -326,6 +326,7 @@ async fn beta_reduce<'a>(
                             None,
                             None,
                             None,
+                            None, // tags
                             env.env_vars.clone(),
                             TripWire::new(None),
                         )
@@ -1159,6 +1160,7 @@ test Poems {
                 Some(on_event),
                 None,
                 HashMap::new(),
+                None,
                 TripWire::new(None),
                 None::<Box<dyn Fn()>>,
             )
@@ -1293,6 +1295,7 @@ test TestMakePerson() {
                 Some(on_event),
                 None,
                 HashMap::new(),
+                None,
                 TripWire::new(None),
                 None::<Box<dyn Fn()>>,
             )
@@ -1371,6 +1374,7 @@ test UseFunction() {
                     "OPENAI_API_KEY".to_string(),
                     std::env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY is not set."),
                 )]),
+                None,
                 TripWire::new(None),
                 None::<Box<dyn Fn()>>,
             )

engine/baml-runtime/src/lib.rs

@@ -452,6 +452,7 @@ impl BamlRuntime {
         expr_tx: Option<mpsc::UnboundedSender<Vec<internal_baml_diagnostics::SerializedSpan>>>,
         collector: Option<Arc<Collector>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         cancel_tripwire: Arc<TripWire>,
         on_tick: Option<G>,
     ) -> (Result<TestResponse>, FunctionCallId)
@@ -471,6 +472,7 @@ impl BamlRuntime {
                 true,
                 true, // tests always stream which is why there's an on_event
                 collector.as_ref().map(|c| vec![c.clone()]),
+                tags.as_ref(),
             );
 
         let expr_fn = self.inner.ir().find_expr_fn(function_name);
@@ -576,6 +578,7 @@ impl BamlRuntime {
                 self.async_runtime.clone(),
                 // TODO: collectors here?
                 vec![],
+                None, // tags
                 cancel_tripwire,
             )?;
             let (response_res, call_uuid) = stream
@@ -673,6 +676,7 @@ impl BamlRuntime {
         on_event: Option<F>,
         collector: Option<Arc<Collector>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         cancel_tripwire: Arc<TripWire>,
         on_tick: Option<G>,
     ) -> (Result<TestResponse>, FunctionCallId)
@@ -689,6 +693,7 @@ impl BamlRuntime {
                 None,
                 collector,
                 env_vars,
+                tags,
                 cancel_tripwire,
                 on_tick,
             )
@@ -706,6 +711,7 @@ impl BamlRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         cancel_tripwire: Arc<TripWire>,
     ) -> (Result<FunctionResult>, FunctionCallId) {
         let fut = self.call_function(
@@ -715,6 +721,7 @@ impl BamlRuntime {
             tb,
             cb,
             collectors,
+            tags,
             env_vars,
             cancel_tripwire,
         );
@@ -729,6 +736,7 @@ impl BamlRuntime {
         tb: Option<&TypeBuilder>,
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
+        tags: Option<HashMap<String, String>>,
         env_vars: HashMap<String, String>,
         cancel_tripwire: Arc<TripWire>,
     ) -> (Result<FunctionResult>, FunctionCallId) {
@@ -742,6 +750,7 @@ impl BamlRuntime {
             env_vars,
             None,
             cancel_tripwire,
+            tags,
         ))
         .await;
         res
@@ -779,6 +788,7 @@ impl BamlRuntime {
         env_vars: HashMap<String, String>,
         expr_tx: Option<mpsc::UnboundedSender<Vec<internal_baml_diagnostics::SerializedSpan>>>,
         cancel_tripwire: Arc<TripWire>,
+        tags: Option<HashMap<String, String>>,
     ) -> (Result<FunctionResult>, FunctionCallId) {
         // baml_log::info!("env vars: {:#?}", env_vars.clone());
         baml_log::set_from_env(&env_vars).unwrap();
@@ -789,7 +799,15 @@ impl BamlRuntime {
         let call = self
             .tracer_wrapper
             .get_or_create_tracer(&env_vars)
-            .start_call(&function_name, ctx, params, true, false, collectors);
+            .start_call(
+                &function_name,
+                ctx,
+                params,
+                true,
+                false,
+                collectors,
+                tags.as_ref(),
+            );
         let curr_call_id = call.curr_call_id();
 
         let fake_syntax_span = Span::fake();
@@ -984,6 +1002,7 @@ impl BamlRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         expr_tx: Option<mpsc::UnboundedSender<Vec<SerializedSpan>>>,
         cancel_tripwire: Arc<TripWire>,
     ) -> Result<FunctionResultStream> {
@@ -996,6 +1015,7 @@ impl BamlRuntime {
             #[cfg(not(target_arch = "wasm32"))]
             self.async_runtime.clone(),
             collectors.unwrap_or_default(),
+            tags,
             cancel_tripwire,
         )
     }
@@ -1009,6 +1029,7 @@ impl BamlRuntime {
         cb: Option<&ClientRegistry>,
         collectors: Option<Vec<Arc<Collector>>>,
         env_vars: HashMap<String, String>,
+        tags: Option<HashMap<String, String>>,
         cancel_tripwire: Arc<TripWire>,
     ) -> Result<FunctionResultStream> {
         self.stream_function_with_expr_events(
@@ -1019,6 +1040,7 @@ impl BamlRuntime {
             cb,
             collectors,
             env_vars,
+            tags,
             None,
             cancel_tripwire,
         )
@@ -1330,7 +1352,7 @@ impl ExperimentalTracingInterface for BamlRuntime {
     ) -> TracingCall {
         self.tracer_wrapper
             .get_or_create_tracer(env_vars)
-            .start_call(function_name, ctx, params, false, false, None)
+            .start_call(function_name, ctx, params, false, false, None, None)
     }
 
     #[cfg(not(target_arch = "wasm32"))]
@@ -1505,7 +1527,7 @@ async fn expr_eval_result(
         Ok(expr_fn) => {
             log::trace!("Calling function: {function_name}");
             let collectors = collector.as_ref().map(|c| vec![c.clone()]);
-            let call = tracer.start_call(function_name, mgr, params, true, false, collectors);
+            let call = tracer.start_call(function_name, mgr, params, true, false, collectors, None);
 
             let ctx = mgr.create_ctx(tb, cb, env_vars.clone(), call.new_call_id_stack.clone())?;
             let env = EvalEnv {

engine/baml-runtime/src/runtime_methods/stream_function.rs

@@ -50,6 +50,7 @@ impl InternalBamlRuntime {
         ctx: RuntimeContext,
         #[cfg(not(target_arch = "wasm32"))] tokio_runtime: Arc<tokio::runtime::Runtime>,
         collectors: Vec<Arc<Collector>>,
+        tags: Option<HashMap<String, String>>,
         cancel_tripwire: Arc<TripWire>,
     ) -> Result<FunctionResultStream> {
         let is_expr_fn = self.get_expr_function(&function_name, &ctx).is_ok();
@@ -84,6 +85,7 @@ impl InternalBamlRuntime {
                 #[cfg(not(target_arch = "wasm32"))]
                 tokio_runtime,
                 collectors,
+                tags,
                 cancel_tripwire,
             })
         } else {
@@ -104,6 +106,7 @@ impl InternalBamlRuntime {
                 #[cfg(not(target_arch = "wasm32"))]
                 tokio_runtime,
                 collectors,
+                tags,
                 cancel_tripwire,
             })
         }

engine/baml-runtime/src/test_executor/mod.rs

@@ -294,6 +294,7 @@ impl TestExecutor for BamlRuntime {
                             on_event,
                             None,
                             env_vars,
+                            None,                // tags
                             TripWire::new(None), // No tripwire for test executor,
                             on_tick,
                         )

engine/baml-runtime/src/tests.rs

@@ -90,7 +90,17 @@ async fn test_call_function() -> Result<FunctionResult> {
     );
 
     let (res, _) = runtime
-        .call_function("ExtractNames".to_string(), &params, &ctx)
+        .call_function(
+            "ExtractNames".to_string(),
+            &params,
+            &ctx,
+            None,
+            None,
+            None,
+            None, // tags
+            std::env::vars().collect(),
+            stream_cancel::Tripwire::new(None),
+        )
         .await;
     let res = res?;
 

engine/baml-runtime/src/tracing/mod.rs

@@ -408,9 +408,23 @@ impl BamlTracer {
         is_stream: bool,
         // baml_src_hash: Option<String>,
         collectors: Option<Vec<Arc<Collector>>>,
+        tags: Option<&HashMap<String, String>>,
     ) -> TracingCall {
         self.trace_stats.guard().start();
-        let (call_id, call_stack, last_tags, global_tags) = ctx.enter(function_name);
+        let (call_id, call_stack, mut ctx_tags, global_tags) = ctx.enter(function_name);
+
+        if let Some(tag_map) = tags {
+            if !tag_map.is_empty() {
+                log::debug!("start_call: incoming tags: {:#?}", tag_map);
+                let tag_values: HashMap<String, BamlValue> = tag_map
+                    .iter()
+                    .map(|(k, v)| (k.clone(), BamlValue::String(v.clone())))
+                    .collect();
+                ctx.upsert_tags(tag_values.clone());
+                ctx_tags.extend(tag_values);
+                log::debug!("start_call: ctx_tags after extend: {:#?}", ctx_tags);
+            }
+        }
 
         log::trace!(
             "\n{}------------------- Entering {:?}, ctx chain {:#?}",
@@ -427,7 +441,7 @@ impl BamlTracer {
             start_time: web_time::SystemTime::now(),
             // Note these tags are the ones currently on the stack. While the function runs we may register
             // more tags with set_tags(). Those are picked up via a diff event (SetTags)
-            tags: last_tags.clone(),
+            tags: ctx_tags.clone(),
         };
         // println!("---- {} ctx {:#?}", function_name, ctx);
         // baml_log::info!("---- {} ctx {:#?}", function_name, ctx);
@@ -460,7 +474,7 @@ impl BamlTracer {
             EvaluationContext {
                 tags: global_tags
                     .into_iter()
-                    .chain(last_tags)
+                    .chain(ctx_tags)
                     .map(|(k, v)| (k, serde_json::to_value(v).unwrap_or_default()))
                     .collect(),
             },

engine/baml-runtime/src/tracingv2/storage/storage.rs

@@ -520,6 +520,11 @@ impl FunctionLog {
     pub fn metadata(&mut self) -> HashMap<String, serde_json::Value> {
         self.get_inner().lock().unwrap().metadata.clone()
     }
+
+    /// Backwards-compatible alias for metadata used by some language clients as "tags"
+    pub fn tags(&mut self) -> HashMap<String, serde_json::Value> {
+        self.get_inner().lock().unwrap().metadata.clone()
+    }
 }
 
 impl Drop for FunctionLog {