--- name: bijection-convex-langfuse description: "Evaluate and integrate the Convex Langfuse component with Bijection." --- # Convex Langfuse Send LLM traces, generations, and scores from Convex to Langfuse over OpenTelemetry, with a reactive local copy of the data. This is an upstream package. It has not been adapted or qualified for Bijection. - Package: convex-langfuse - Source: https://github.com/sholajegede/convex-langfuse - npm: https://www.npmjs.com/package/convex-langfuse - Directory: https://bijection.com/components/convex-langfuse 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-langfuse. 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 Convex Langfuse. Follow the installation and configuration steps exactly. # Convex Langfuse ## Instructions convex-langfuse bridges Convex actions and Langfuse observability by exporting completed LLM calls as OpenTelemetry spans via Langfuse's OTLP/HTTP endpoint, bypassing the deprecated batch ingestion API. Because Convex actions are stateless and short-lived, the component accepts already-finished input/output/token data rather than managing open spans. Every trace, observation, and score is also written to Convex tables, enabling reactive queries over your LLM history without additional Langfuse API calls. ### Installation ```bash npm install convex-langfuse ``` Current npm version: `convex-langfuse@0.0.5` ## Use cases - Logging completed LLM generations from Convex actions, including model name, token counts, and prompt/completion text, for cost and quality monitoring in Langfuse - Grouping a retrieval step and a generation step under a single Langfuse trace by passing the same traceId across multiple logSpan and logGeneration calls - Attaching user thumbs-up/thumbs-down ratings or automated eval scores to a trace after the fact using recordScore - Building a reactive in-app trace history or token usage dashboard by querying the mirrored Convex tables with listRecentTraces or getStats without hitting the Langfuse API - Migrating LLM observability off Langfuse's deprecated batch ingestion endpoint before the November 2026 sunset by switching to the OTLP-native integration ## How it works After installing the package and registering the component in convex.config.ts, you initialize a Langfuse client with your Langfuse public and secret keys. The client exposes action-callable methods: logGeneration for completed LLM calls and logSpan for non-LLM pipeline steps. Each call accepts a finished payload including input, output, token counts, and optional trace-scoping fields like userId and sessionId. Under the hood, each logGeneration or logSpan call constructs a minimal OTLP/HTTP JSON payload using Langfuse's documented span attribute conventions and exports it to Langfuse's OTLP endpoint via fetch, with no OpenTelemetry SDK dependency. The component targets the OTLP endpoint rather than the deprecated /api/public/ingestion batch endpoint, so it remains compatible after the November 2026 cloud sunset. Alongside the export, each call writes a record into the component's own Convex tables: traces, observations, and scores. These tables are queryable through provided query helpers such as getTrace, listObservations, listTracesByUser, and getStats, which means your frontend can subscribe to LLM activity reactively using standard Convex query patterns. The recordScore method posts a score to Langfuse's Scores REST endpoint and mirrors it locally in the same way. ## 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 Convex Langfuse is not needed ## Resources - [npm package](https://www.npmjs.com/package/convex-langfuse) - [GitHub repository](https://github.com/sholajegede/convex-langfuse) - [Live demo](https://convex-langfuse.vercel.app) - [Convex Components Directory](https://www.convex.dev/components/convex-langfuse) - [Convex documentation](https://docs.convex.dev)