Instrument a Backend Flow with Failpath End to End

This guide walks you through instrumenting a backend function with Failpath from scratch. You will initialize the CLI, inspect the generated flow definition, install the SDK, create a client, wrap your business steps, and publish your flow so events appear on your dashboard.

Initialize your project

Run the following command in the root of your backend repository, replacing fp_project_xxx with your actual project key:

npx failpath init --project-key fp_project_xxx

The init command does five things:

Writes FAILPATH_PROJECT_KEY to a .env file
Adds .env to your .gitignore
Creates .failpath/AGENTS.md
Pulls your project’s current dashboard graph into .failpath/flows.json
Generates .failpath/sdk.ts for typed flow and step keys

Inspect the generated flow keys

Open .failpath/flows.json. You will see one or more flow objects. Two fields are important when writing SDK code:

flow.slug — pass this string as the first argument to run(). It identifies which flow a run belongs to.
node.sdkStepKey — pass this string as the first argument to step(). It maps a recorded event to a specific node on your dashboard graph.

{
  "flows": [
    {
      "slug": "checkout",
      "nodes": [
        { "sdkStepKey": "validate-cart", "label": "Validate Cart" },
        { "sdkStepKey": "charge-card", "label": "Charge Card" },
        { "sdkStepKey": "send-receipt-email", "label": "Send Receipt Email" }
      ]
    }
  ]
}

The CLI also generates .failpath/sdk.ts from this graph. Import failpathFlows from that file when you instrument code so the slugs and step keys autocomplete.

Install @failpath/sdk

Add the SDK to your project:

npm install @failpath/sdk

pnpm add @failpath/sdk

bun add @failpath/sdk

Create the client

Create the Failpath client once at the module level and export it as a singleton. Importing the same instance across your codebase ensures that configuration — like defaultMetadata — is applied consistently everywhere.

// lib/failpath.ts
import { createTypedFailpathClient } from "../.failpath/sdk";

export const failpath = createTypedFailpathClient({
  projectKey: process.env.FAILPATH_PROJECT_KEY!,
  defaultMetadata: { environment: "production" },
});

The projectKey is read from the environment variable written by npx failpath init. In local development your .env file supplies it automatically.

Wrap your function steps

Import your client and failpathFlows, then use run() to start a run and wrap each business step with step(). Reuse the same runId for every step that belongs to the same request.

import { failpathFlows } from "../.failpath/sdk";
import { failpath } from "./lib/failpath";

export async function handleCheckout(requestId: string) {
  const run = failpath.run(failpathFlows.checkout.slug, {
    runId: requestId,
    metadata: { route: "/checkout" },
  });

  const cart = await run.step(failpathFlows.checkout.steps.validateCart, async () => {
    return validateCart();
  });

  const charge = await run.step(failpathFlows.checkout.steps.chargeCard, async () => {
    return chargeCard(cart);
  });

  await run.step(failpathFlows.checkout.steps.sendReceiptEmail, async () => {
    return sendReceiptEmail(charge.receiptAddress);
  });

  await failpath.flush();
}

Each step() call queues a running event before the wrapped operation executes, then queues success or error when it finishes. Sends run in the background by default, so call flush() before a short-lived request, job, or script exits unless your runtime keeps background work alive with waitUntil.

Wrap business steps like validateCart, chargeCard, and sendReceiptEmail — not tiny helpers, utility functions, or repository calls. Each wrapped step should represent a meaningful unit of work you want to track on your dashboard.

Publish and view your dashboard

Push your local flow definition to Failpath:

npx failpath publish

Then trigger your function — call the endpoint, run the job, or fire the webhook — and open your Failpath dashboard. You will see the run appear with success or error status on each step node.

Get Started

Core Concepts

CLI

SDK

Guides

Instrument a Backend Flow with Failpath End to End