Ryan KatayiSenior full-stack engineer
    All sessions

    Engineering notes — ExplainersInstrument Vercel Daemons with OpenTelemetry tracing

    How to send OpenTelemetry traces from Vercel Daemons to Vercel Tracing so your background workers show up alongside your Next.js app traces.

    8 min

    #Vercel#Next.js#Node.js#TypeScript

    Vercel Daemons can now send OpenTelemetry traces directly into Vercel Tracing. That means your background workers can show up in the same trace view as your Next.js API routes and route handlers. The integration is simple if you're already using Vercel's @vercel/otel package.

    This post walks through what actually happens under the hood, how to wire up a daemon, and how to search for its spans from the CLI so your agents can consume them.

    What changed for Vercel Daemons tracing?

    Vercel's changelog describes the change in one line:

    "Vercel Daemons can now send OpenTelemetry traces to Vercel Tracing, allowing you and your agents to inspect background worker operations alongside the rest of your project's traces."

    — Vercel changelog

    The core pieces:

    1. Each daemon now gets a Unix socket for OTLP/HTTP traces. Vercel sets the path to that socket in the VERCEL_OTEL_SOCKET_PATH environment variable.
    2. @vercel/otel v2.3.0+ knows how to use that socket. When you upgrade and call registerOTel in a Node.js daemon, the SDK detects the socket and exports spans to Vercel Tracing with its default configuration.
    3. You can query those spans by service name. The vercel traces search CLI command accepts a --service flag and can return JSON for whatever is consuming your traces, including agents.

    If your Next.js app already emits traces to Vercel Tracing, this lets your daemons participate in the same trace stream. You can track a path that starts in an API route, enqueues some work for a daemon, and finishes when the worker is done.

    How Vercel Daemons send OTLP/HTTP traces

    The mechanism is straightforward.

    1. Daemon boots, Vercel injects a socket path. When Vercel runs your daemon, it provides a Unix domain socket dedicated to OTLP/HTTP traces and sets VERCEL_OTEL_SOCKET_PATH to that path.
    2. Your daemon initializes @vercel/otel. You call registerOTel at startup, before you start doing real work.
    3. @vercel/otel detects the socket Vercel exposed. The SDK configures an OTLP/HTTP exporter that uses that Unix socket when it is available.
    4. Your code creates spans as usual. You instrument your background work with OpenTelemetry APIs (for example, @opentelemetry/api in Node). @vercel/otel wires those spans to its exporter.
    5. The exporter streams spans over OTLP/HTTP to Vercel. The spans travel through the Unix socket into Vercel Tracing and end up associated with your project.

    Conceptually, the flow looks like this:

    [Daemon process]
       |   env: VERCEL_OTEL_SOCKET_PATH=<path set by Vercel>
       v
    @vercel/otel (registerOTel)
       |
       |  OTLP/HTTP over Unix socket
       v
    [Unix socket provided by Vercel]
       |
       v
    [Vercel Tracing backend] -> project traces

    The important detail is that you don't have to configure endpoints or exporters yourself for daemons. On Vercel, you let the SDK discover the socket and use the defaults.

    This doesn't cover non-Node daemons. Vercel explicitly calls out "automatic trace export for Node.js daemons" when using @vercel/otel 2.3.0 or later.

    Instrumenting a daemon with @vercel/otel

    Vercel's post shows the minimal wiring for a daemon worker:

    // worker.ts
    import { registerOTel } from '@vercel/otel';
    
    registerOTel({ serviceName: 'my-daemon' });
    
    // Initialize OpenTelemetry before the worker starts.

    A few practical points when you drop this into a real worker:

    1. Call registerOTel at the very top. It needs to run before your daemon begins its main loop or schedules recurring work. That way, any spans you create from the start of the process can be exported.
    2. Pick a stable serviceName. This name is how you'll filter spans later. For one background worker per project, a name like emails-daemon or billing-worker works well.
    3. Keep the rest of your tracing setup normal. Your actual spans still come from regular OpenTelemetry APIs in your code. registerOTel just configures the export path to Vercel.

    On the daemon side, you don't have to reference VERCEL_OTEL_SOCKET_PATH manually. The SDK handles it. The environment variable only matters as a signal that you're running inside Vercel with tracing enabled.

    Viewing daemon traces alongside your Next.js app

    Once your daemon is emitting spans, the next step is to observe them next to your Next.js app traces.

    According to Vercel's changelog:

    "These spans are available through the Vercel CLI, which can search by service name within a project and return JSON for your agents."

    — Vercel changelog

    The CLI command Vercel shows looks like this:

    vercel traces search --project my-project --service my-daemon --json

    That will:

    • Search for traces within the given project.
    • Filter them by the serviceName you passed to registerOTel (here, my-daemon).
    • Return the results as JSON, which is convenient if you have agents or scripts consuming trace data.

    For a typical Next.js app on Vercel, you'd:

    • Have your Next.js routes and handlers already integrated with Vercel Tracing.
    • Give your daemon a specific serviceName like background-sync.
    • Use the CLI to confirm the daemon is emitting spans while also using the Vercel UI to look at request traces from the app.

    That lets you check that background work triggered by API calls is visible in the same project-level trace set, even if the exact linking between specific requests and daemon spans depends on how you propagate context in your code.

    It's the kind of visibility I'd want on a larger Next.js product such as Axlow's document search app, where request handling and background processing both matter.

    Trying it: minimal setup

    Here's a minimal end-to-end flow you can follow using the snippets Vercel published.

    1. Upgrade @vercel/otel.

      Make sure your daemon's package.json depends on @vercel/otel version 2.3.0 or later. Vercel says that automatic export kicks in starting from 2.3.0.

    2. Add tracing initialization to your daemon.

      Import and call registerOTel near the top of your daemon entry file, passing a serviceName that you'll later use to filter traces.

      Then start your actual daemon logic below it.

    3. Deploy your daemon to Vercel.

      Deploy as you normally would for a Vercel Daemon so it runs in the background for your project.

    4. Generate some work that emits spans.

      Run whatever code path in your daemon records spans via your OpenTelemetry instrumentation.

    5. Search for the daemon spans via CLI.

      From your terminal, use the vercel traces search command with your project name and the daemon's serviceName, and request JSON output for easier inspection or agent consumption.

    If the command returns JSON spans, your daemon is successfully sending traces to Vercel Tracing over the Unix socket Vercel provided.

    Local debugging tips for your worker

    Vercel's post focuses on how tracing works inside their environment and doesn't cover local development for daemons. You still want a way to reason about your tracing setup before you deploy.

    Some general patterns that help when you're working with OpenTelemetry in a Node.js worker:

    1. Keep initialization isolated. Wrap the call to registerOTel in its own module that you import at the top of your worker. That makes it easy to stub or adjust tracing behavior locally without touching your business logic.
    2. Guard Vercel-specific behavior. If you branch on process.env.VERCEL_OTEL_SOCKET_PATH in your code for any reason, keep that branching close to the tracing setup. Everywhere else in your worker should just depend on generic OpenTelemetry APIs.
    3. Log span context when debugging. When you're trying to understand how background work relates to an incoming request, logging correlation IDs or trace IDs from your spans can help you follow the chain when looking at traces from multiple services.

    Those habits keep the difference between "running as a Vercel Daemon" and "running locally" small and visible, which is important when you come back to the code months later.

    If your Next.js backend is already in place, this is mostly an incremental change: add registerOTel to your daemon and check spans with the CLI.

    When I wouldn’t rely on this setup

    There are a few situations where I’d pause before wiring up daemon tracing this way:

    • Non-Node daemons. The automatic export described by Vercel is for Node.js daemons using @vercel/otel. If your worker isn’t Node-based, you’ll need a different plan.
    • No OpenTelemetry in the rest of your stack. If your Next.js app and other services don’t use tracing at all yet, I’d start with instrumenting your public-facing requests before spending time on background jobs.
    • Very short-lived or trivial daemons. If a daemon does a tiny, constant-time task with no variability or user impact, traces may not tell you much beyond basic logging.

    For most real products with background work tied to user actions, though, having the daemon show up in the same trace surface as your Next.js handlers is worth the small amount of setup.

    Being able to see background workers in Vercel Tracing, and query them by service name from the CLI, closes a visibility gap I see in a lot of projects. If you’re running a Next.js app on Vercel and using Daemons for real work, I’d wire this up early and use it as part of your standard debugging toolkit. If you want help fitting this into a broader Next.js architecture, you can start a conversation on my Next.js developer services page.

    Sources

    Now playingCudioGet in touch