sentry-span-streaming

Q: How do I install sentry-span-streaming?

Run npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-span-streaming in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sentry-span-streaming/ (personal) or .claude/skills/sentry-span-streaming/ (project).

by getsentryDevOps & Cloud

Migrate to Sentry span streaming (span-first trace lifecycle). Use when asked to "enable span streaming", "migrate to span streaming", "use traceLifecycle stream", "add spanStreamingIntegration", or switch from transaction-based to streamed span delivery.

Installs: 59
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-span-streaming

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads sentry-span-streaming automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

All Skills > Feature Setup > Span Streaming

Sentry Span Streaming Migration

Migrate from the default transaction-based trace lifecycle (static) to span streaming (stream), where spans are sent in multiple batches as they complete instead of being batched into one transaction at the end.

Invoke This Skill When

User asks to "enable span streaming" or "migrate to span streaming"
User wants to switch from transaction-based to streamed span delivery
User mentions traceLifecycle, spanStreamingIntegration, or withStreamedSpan
User wants lower latency span delivery or per-span processing

Supported Platforms

Platform	Status
JavaScript (Browser, Node.js, Bun, Deno, Cloudflare)	Supported
Python	Not yet available
Ruby	Not yet available
Go	Not yet available
Other SDKs	Not yet available

If the user's project does not use a supported SDK, inform them that span streaming is currently only available for JavaScript SDKs and stop here.

Phase 1: Detect

Identify the user's platform, SDK version, and current tracing configuration.

1.1 Detect Platform and SDK

# Check for JavaScript Sentry packages
cat package.json 2>/dev/null | grep -E '"@sentry/'

# Check for Python Sentry
cat requirements.txt setup.py pyproject.toml 2>/dev/null | grep -i sentry

# Check for Ruby Sentry
cat Gemfile 2>/dev/null | grep sentry

# Check for Go Sentry
cat go.mod 2>/dev/null | grep sentry

If an unsupported Sentry SDK is detected, inform the user that span streaming is not yet available for their platform.

1.2 Detect JavaScript Environment

# Detect if browser, server, or both
grep -rn "from '@sentry/browser'\|from '@sentry/react'\|from '@sentry/vue'\|from '@sentry/angular'\|from '@sentry/svelte'\|from '@sentry/nextjs'\|from '@sentry/nuxt'\|from '@sentry/sveltekit'\|from '@sentry/remix'\|from '@sentry/solidstart'\|from '@sentry/astro'\|from '@sentry/react-router'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null | head -20

grep -rn "from '@sentry/node'\|from '@sentry/bun'\|from '@sentry/deno'\|from '@sentry/cloudflare'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null | head -20

1.3 Find Existing Sentry Config

# Find Sentry.init calls
grep -rn "Sentry\.init\|init({" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null | head -20

# Find beforeSendSpan usage
grep -rn "beforeSendSpan" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null

# Find beforeSendTransaction usage
grep -rn "beforeSendTransaction" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null

# Find ignoreSpans usage
grep -rn "ignoreSpans" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null

1.4 Classify Environment

Based on detection results, classify each Sentry.init call as:

Environment	Packages	Migration Path
Browser	`@sentry/browser`, `@sentry/react`, `@sentry/vue`, `@sentry/angular`, `@sentry/svelte`	Add `spanStreamingIntegration()`
Server	`@sentry/node`, `@sentry/bun`, `@sentry/deno`, `@sentry/cloudflare`	Add `traceLifecycle: 'stream'`
Framework (both)	`@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/remix`, `@sentry/astro`, `@sentry/solidstart`, `@sentry/react-router`	Migrate both client and server configs separately

Phase 2: Migrate (JavaScript)

Prerequisites: Sentry JavaScript SDK >=10.53.1 with tracing enabled (tracesSampleRate or tracesSampler configured).

Apply changes to each Sentry.init call. Work through each file identified in Phase 1.

2.1 Enable Span Streaming

Server-Side SDKs

Add traceLifecycle: 'stream' to Sentry.init():

// Before
Sentry.init({
  dsn: '...',
  tracesSampleRate: 1.0,
});

// After
Sentry.init({
  dsn: '...',
  tracesSampleRate: 1.0,
  traceLifecycle: 'stream',
});

Browser-Side SDKs

Add Sentry.spanStreamingIntegration() to the integrations array. The integration automatically enables traceLifecycle: 'stream' — you do not need to set it manually.

// Before
Sentry.init({
  dsn: '...',
  integrations: [
    Sentry.browserTracingIntegration(),
  ],
  tracesSampleRate: 1.0,
});

// After
Sentry.init({
  dsn: '...',
  integrations: [
    Sentry.spanStreamingIntegration(),
    Sentry.browserTracingIntegration(),
  ],
  tracesSampleRate: 1.0,
});

The order of spanStreamingIntegration() relative to other integrations does not matter.

Framework SDKs (Client + Server)

Apply the browser migration to client config files and the server migration to server config files. Common patterns:

Framework	Client Config	Server Config
Next.js	`sentry.client.config.ts`	`sentry.server.config.ts`, `sentry.edge.config.ts`
Nuxt	Client-side `Sentry.init` in module	Server-side `Sentry.init` in module
SvelteKit	`src/hooks.client.ts`	`src/hooks.server.ts`
Remix	`entry.client.tsx`	`entry.server.tsx`
Astro	Client-side init	Server-side init

2.2 Migrate `beforeSendSpan`

If the user has a beforeSendSpan callback, it must be wrapped with Sentry.withStreamedSpan() to work in streaming mode. Without this wrapper, the SDK falls back to static mode.

The callback shape also changes:

description is now name
data is now attributes
The span object is StreamedSpanJSON instead of SpanJSON

// Before (static mode)
Sentry.init({
  beforeSendSpan: (span) => {
    if (span.description?.includes('/health')) {
      span.description = '[filtered]';
    }
    // 'data' contains span attributes
    delete span.data?.['http.request.body'];
    return span;
  },
});

// After (streaming mode)
Sentry.init({
  beforeSendSpan: Sentry.withStreamedSpan((span) => {
    if (span.name?.includes('/health')) {
      span.name = '[filtered]';
    }
    // 'attributes' replaces 'data'
    if (span.attributes) {
      delete span.attributes['http.request.body'];
    }
    return span;
  }),
});

Key differences in the callback:

Static (`SpanJSON`)	Streaming (`StreamedSpanJSON`)
`span.description`	`span.name`
`span.data` (processed attributes)	`span.attributes` (raw attributes)
`span.timestamp` (end time)	`span.end_timestamp`
`span.status` (optional string)	`span.status` (`'ok'` or `'error'`)
`span.op`	`span.attributes['sentry.op']`

Returning null from beforeSendSpan does not drop the span — it is ignored and a warning is logged.

2.3 Remove or Replace `beforeSendTransaction`

beforeSendTransaction has no effect in streaming mode. Spans are sent individually, not batched into transactions.

// Before
Sentry.init({
  beforeSendTransaction: (event) => {
    // This entire callback is ignored in streaming mode
    if (event.transaction === '/health') {
      return null;
    }
    return event;
  },
});

Migration paths depending on what beforeSendTransaction was used for:

Use Case	Streaming Replacement
Drop spans by name/route	Use `ignoreSpans` option
Modify span data before send	Use `beforeSendSpan` with `withStreamedSpan`
Filter by transaction name	Use `ignoreSpans` with string/RegExp pattern
Add tags/context to transaction	Use `beforeSendSpan` with `withStreamedSpan`

Remove the beforeSendTransaction option from Sentry.init() after migrating its logic.

2.4 Configure `ignoreSpans` (Optional)

ignoreSpans works in both static and streaming modes, but the filter is evaluated at different points in the span lifecycle:

Streaming mode: evaluated when the span starts. Only data available at span start — the span name and the attributes set at creation — is taken into account.
Static mode: evaluated when the root span ends. Only data available at that point — the span name and attributes — is taken into account.

In both modes, a match prevents the span from being recorded or sent. Because matching can run as early as span start (streaming), only the span name and attributes set when the span begins are guaranteed to be available — do not rely on attributes added later in the span's lifetime.

Sentry.init({
  traceLifecycle: 'stream',
  ignoreSpans: [
    // String match against span name
    '/health',
    '/ready',

    // RegExp match against span name
    /^OPTIONS /,

    // Object filter — all conditions must match
    {
      op: 'middleware.handle',
      name: /^corsMiddleware/,
    },

    // Filter by attributes (string = substring match, RegExp for patterns)
    {
      op: 'http.server',
      attributes: {
        'http.route': /^\/internal\//,
      },
    },
  ],
});

Filter object properties:

Property	Type	Matches Against
`name`	`string \| RegExp`	Span name (description)
`op`	`string \| RegExp`	Span operation
`attributes`	`Record<string, string \| RegExp \| number \| boolean \| Array>`	Span attributes

When multiple properties are specified in a filter object, all must match for the span to be ignored.

2.5 Set Up Browser Profiling (Optional)

When using span streaming in the browser, use the v2 profiling options — not the legacy profilesSampleRate. The legacy option is deprecated and does not integrate with the span streaming lifecycle.

Add browserProfilingIntegration() and configure the two v2 options:

// Before (legacy profiling — do NOT use with span streaming)
Sentry.init({
  integrations: [
    Sentry.browserTracingIntegration(),
  ],
  tracesSampleRate: 1.0,
  profilesSampleRate: 0.5, // deprecated
});

// After (v2 profiling with span streaming)
Sentry.init({
  integrations: [
    Sentry.spanStreamingIntegration(),
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
  profileLifecycle: 'trace',
});

v2 profiling options:

Option	Type	Description
`profileSessionSampleRate`	`number` (0–1)	Percentage of user sessions that have profiling enabled. Default: `0` (disabled).
`profileLifecycle`	`'trace' \| 'manual'`	`'trace'`: profiler runs automatically while sampled root spans exist. `'manual'`: start/stop profiler explicitly via `Sentry.uiProfiler.startProfiler()` / `stopProfiler()`. Default: `'manual'`.

profileLifecycle: 'trace' requires tracing to be enabled (tracesSampleRate or tracesSampler). The profiler starts when a root span begins and stops when no sampled root spans remain. Profile chunks are sent independently every 60 seconds or when the last root span ends.

Do not mix legacy and v2 options. If profilesSampleRate is set, profileSessionSampleRate has no effect and the SDK logs a warning.

Phase 3: Verify

After applying changes, verify the migration works correctly.

3.1 Build Check

# TypeScript check
npx tsc --noEmit 2>&1 | head -30

# Build
npm run build 2>&1 | tail -20

3.2 Runtime Verification

Instruct the user to verify in their browser devtools or server logs:

Check network tab: Span envelopes should appear as individual requests with content type application/vnd.sentry.items.span.v2+json rather than transaction envelopes
Check Sentry dashboard: Spans should appear in the Traces view shortly after they complete, without waiting for the full transaction to finish
Check for fallback warnings: If the SDK logs warnings about falling back to static mode, the beforeSendSpan callback is likely missing the withStreamedSpan wrapper

3.3 Common Issues

Symptom	Cause	Fix
SDK falls back to static mode	`beforeSendSpan` not wrapped with `withStreamedSpan`	Wrap callback: `Sentry.withStreamedSpan(callback)`
`beforeSendTransaction` not called	Expected in streaming mode	Migrate logic to `beforeSendSpan` or `ignoreSpans`
Spans still arrive as transactions	`traceLifecycle` not set or integration missing	Server: add `traceLifecycle: 'stream'`; Browser: add `spanStreamingIntegration()`
Type errors on `span.description`	`StreamedSpanJSON` uses `name` not `description`	Change `span.description` to `span.name` in callback
Type errors on `span.data`	`StreamedSpanJSON` uses `attributes` not `data`	Change `span.data` to `span.attributes` in callback
`profileSessionSampleRate` has no effect	Legacy `profilesSampleRate` is also set	Remove `profilesSampleRate` and use only `profileSessionSampleRate` + `profileLifecycle`

Quick Reference (JavaScript)

Minimal Server Setup

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: '__DSN__',
  tracesSampleRate: 1.0,
  traceLifecycle: 'stream',
});

Minimal Browser Setup

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: '__DSN__',
  integrations: [
    Sentry.spanStreamingIntegration(),
    Sentry.browserTracingIntegration(),
  ],
  tracesSampleRate: 1.0,
});

Browser Setup with Profiling

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: '__DSN__',
  integrations: [
    Sentry.spanStreamingIntegration(),
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
  profileLifecycle: 'trace',
});

Full Migration Checklist

FAQ

What does the sentry-span-streaming skill do?

How do I install sentry-span-streaming?

Run npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-span-streaming in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sentry-span-streaming/ (personal) or .claude/skills/sentry-span-streaming/ (project).

Which AI agents can use sentry-span-streaming?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is sentry-span-streaming safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains sentry-span-streaming?

It is published by getsentry in getsentry/sentry-for-ai. It has 59 recorded installs.

More from getsentry/sentry-for-ai

View all →

sentry-fix-issues

getsentry/sentry-for-ai

Find and fix issues from Sentry using MCP. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in Sentry. Methodically analyzes stack traces, breadcrumbs, traces, and context to identify root causes.

OfficialDevOps & Cloud10K installs

sentry-react-native-sdk

getsentry/sentry-for-ai

Full Sentry SDK setup for React Native and Expo. Use when asked to "add Sentry to React Native", "install @sentry/react-native", "setup Sentry in Expo", or configure error monitoring, tracing, profiling, session replay, or logging for React Native applications. Supports Expo managed, Expo bare, and vanilla React Native.

OfficialDevOps & Cloud4.1K installs

sentry-create-alert

getsentry/sentry-for-ai

Create Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow automations. Supports email, Slack, PagerDuty, Discord, and other notification actions.

OfficialDevOps & Cloud4.1K installs

sentry-nextjs-sdk

getsentry/sentry-for-ai

Full Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay, logging, profiling, AI monitoring, or crons for Next.js applications. Supports Next.js 13+ with App Router and Pages Router.

OfficialDevOps & Cloud3.6K installs

sentry-sdk-setup

getsentry/sentry-for-ai

Set up Sentry in any language or framework. Detects the user's platform and loads the right SDK skill. Use when asked to add Sentry, install an SDK, or set up error monitoring in a project.

OfficialDevOps & Cloud3.6K installs

sentry-workflow

getsentry/sentry-for-ai

Keep Sentry SDKs up to date. Use when asked to upgrade the Sentry SDK across major versions, migrate SDK versions, or fix deprecated APIs.

OfficialDevOps & Cloud3.6K installs

Popular devops & cloud skills

View category →

microsoft-foundry

microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure

OfficialDevOps & Cloud579.1K installs

azure-diagnostics

microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.

OfficialDevOps & Cloud569.8K installs

azure-prepare

microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.

OfficialDevOps & Cloud569K installs

azure-ai

microsoft/azure-skills

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

OfficialDevOps & Cloud568.8K installs

azure-deploy

microsoft/azure-skills

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.

OfficialDevOps & Cloud568.6K installs

azure-validate

microsoft/azure-skills

Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.

OfficialDevOps & Cloud568K installs

sentry-span-streaming

Install

Install

Describe the task

Review the result

SKILL.md

Sentry Span Streaming Migration

Invoke This Skill When

Supported Platforms

Phase 1: Detect

1.1 Detect Platform and SDK

1.2 Detect JavaScript Environment

1.3 Find Existing Sentry Config

1.4 Classify Environment

Phase 2: Migrate (JavaScript)

2.1 Enable Span Streaming

Server-Side SDKs

Browser-Side SDKs

Framework SDKs (Client + Server)

2.2 Migrate beforeSendSpan

2.3 Remove or Replace beforeSendTransaction

2.4 Configure ignoreSpans (Optional)

2.5 Set Up Browser Profiling (Optional)

Phase 3: Verify

3.1 Build Check

3.2 Runtime Verification

3.3 Common Issues

Quick Reference (JavaScript)

Minimal Server Setup

Minimal Browser Setup

Browser Setup with Profiling

Full Migration Checklist

FAQ

More from getsentry/sentry-for-ai

Popular devops & cloud skills

2.2 Migrate `beforeSendSpan`

2.3 Remove or Replace `beforeSendTransaction`

2.4 Configure `ignoreSpans` (Optional)