---
name: bijection-convex-tracer
description: "Evaluate and integrate the Tracer component with Bijection."
---

# Tracer

A Tracer component for Convex. Powerful Observability and tracing for Convex applications. Track function calls across queries, mutations, and actions with detailed insights, nested spans, and automa

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-tracer
- Source: https://github.com/Moumen-io/convex-tracer
- npm: https://www.npmjs.com/package/convex-tracer
- Directory: https://bijection.com/components/convex-tracer

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-tracer. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Tracer. Follow the installation and configuration steps exactly.

# Tracer

## Instructions

Convex Tracer adds structured observability to Convex backends by wrapping queries, mutations, and actions with traced equivalents that record spans, logs, and metadata to Convex tables. It supports configurable sample rates, automatic error trace preservation, nested spans, and cross-function trace propagation. Developers get a complete execution timeline for complex multi-step workflows without external observability infrastructure.

### Installation

```bash
npm install convex-tracer
```

Current npm version: `convex-tracer@0.1.3`

## Use cases

- Debugging production failures in multi-step workflows like order processing or payment flows where you need to know exactly which function failed and why
- Tracking cross-function call chains where a single user action triggers several internal mutations and queries that need to be correlated
- Monitoring edge cases conditionally, such as preserving traces only for high-value orders or VIP customers without storing every trace
- Profiling nested database operations within a single function using named spans to identify which sub-operations are slow or failing
- Auditing function argument values and return data selectively with per-function logArgs and logReturn options

## How it works

Install the component by adding it to your `convex.config.ts` with `app.use(tracer)`, then instantiate a `Tracer` class in a shared module like `convex/tracer.ts`. The constructor accepts global options including `sampleRate` (0.0-1.0), `preserveErrors` to always retain error traces, and `retentionMinutes` for automatic cleanup. The instance exports drop-in replacements for standard Convex function definitions: `tracedQuery`, `tracedMutation`, `tracedAction`, and their internal variants.

Each traced function receives an enhanced `ctx` with a `ctx.tracer` object exposing `info`, `warn`, `error`, `updateMetadata`, `preserve`, `discard`, and `withSpan` methods. Nested spans are created with `ctx.tracer.withSpan(name, callback)`, which accepts an async callback receiving a span context with the same logging API, allowing arbitrarily deep nesting.

Cross-function tracing is maintained by using `ctx.runTracedQuery`, `ctx.runTracedMutation`, and `ctx.runTracedAction` instead of the standard `ctx.runQuery` and `ctx.runMutation` helpers. These propagate trace and span IDs automatically so the full call graph appears under a single trace. Per-function overrides for `sampleRate`, `logArgs`, `logReturn`, and lifecycle hooks (`onStart`, `onSuccess`, `onError`) are specified directly on the function definition object.

Note that `tracedQuery` functions run as mutations internally to enable writes to the trace tables, which means they lose Convex query reactivity. Traces are queryable from the backend using `tracer.getTrace` and `tracer.listTraces`, and a `useTracedMutation` React hook is provided for frontend integration.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Tracer is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-tracer)
- [GitHub repository](https://github.com/Moumen-io/convex-tracer)
- [Live demo](https://convex-tracer-demo.vercel.app/)
- [Convex Components Directory](https://www.convex.dev/components/convex-tracer)
- [Convex documentation](https://docs.convex.dev)