Sentry Adapter

Sentry is an error tracking and performance monitoring platform. The evlog Sentry adapter sends your wide events as Sentry Structured Logs, visible in Explore > Logs in the Sentry dashboard with high-cardinality searchable attributes.

Installation

The Sentry adapter comes bundled with evlog:

import { createSentryDrain } from 'evlog/sentry'

Quick Start

1. Get your Sentry DSN

1. Create a Sentry account
2. Create a new project (Node.js or JavaScript)
3. Find your DSN in Settings > Projects > Your Project > Client Keys (DSN)

2. Set environment variables

NUXT_SENTRY_DSN=https://your-public-key@o0.ingest.sentry.io/your-project-id

3. Create the drain plugin

import { createSentryDrain } from 'evlog/sentry'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createSentryDrain())
})

That's it! Your logs will now appear in Explore > Logs in Sentry.

Configuration

The adapter reads configuration from multiple sources (highest priority first):

1. Overrides passed to createSentryDrain()
2. Runtime config at runtimeConfig.evlog.sentry
3. Runtime config at runtimeConfig.sentry
4. Environment variables (NUXT_SENTRY_* or SENTRY_*)

Environment Variables

You can also use SENTRY_DSN, SENTRY_ENVIRONMENT, and SENTRY_RELEASE as fallbacks.

Runtime Config

Configure via nuxt.config.ts for type-safe configuration:

export default defineNuxtConfig({
  modules: ['evlog/nuxt'],
  evlog: {
    sentry: {
      dsn: '', // Set via NUXT_SENTRY_DSN
      environment: 'production',
      release: '1.0.0',
    },
  },
})

Override Options

Pass options directly to override any configuration:

import { createSentryDrain } from 'evlog/sentry'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createSentryDrain({
    dsn: 'https://key@o0.ingest.sentry.io/123',
    tags: { team: 'backend' },
    timeout: 10000, // 10 seconds
  }))
})

Full Configuration Reference

Log Transformation

evlog wide events are converted to Sentry Logs using toSentryLog():

• Level mapping: evlog levels map directly (debug, info, warn, error)
• Severity numbers: Follow the OpenTelemetry spec (debug=5, info=9, warn=13, error=17)
• Body: Derived from the event's message, action, or path fields (first available)
• Attributes: All wide event fields are sent as typed attributes (string, integer, double, boolean). Complex objects are serialized to JSON strings.
• Sentry attributes: sentry.environment and sentry.release are set automatically
• Trace ID: Uses event.traceId if available, otherwise generates a random one

Querying Logs in Sentry

evlog sends wide events as structured logs. In the Sentry dashboard:

• Explore > Logs: View all evlog wide events with full attribute search
• Filter by attributes: service:my-app, level:error, or any wide event field
• Trace correlation: Logs are linked to traces via trace_id for cross-referencing

Troubleshooting

Missing DSN error

[evlog/sentry] Missing DSN. Set NUXT_SENTRY_DSN/SENTRY_DSN env var or pass to createSentryDrain()

Make sure your environment variable is set and the server was restarted after adding it.

Invalid DSN

If the DSN is malformed (missing public key or project ID), the adapter will throw an error. Verify your DSN format:

https://<public-key>@<host>/<project-id>

401 Unauthorized

Your DSN may be revoked or invalid. Generate a new DSN in Settings > Projects > Client Keys (DSN).

Direct API Usage

For advanced use cases, you can use the lower-level functions:

import { sendToSentry, sendBatchToSentry } from 'evlog/sentry'

// Send a single event as a Sentry log
await sendToSentry(event, {
  dsn: process.env.SENTRY_DSN!,
})

// Send multiple events in one request
await sendBatchToSentry(events, {
  dsn: process.env.SENTRY_DSN!,
})

Next Steps

• Axiom Adapter - Send logs to Axiom for querying and dashboards
• OTLP Adapter - Send logs via OpenTelemetry Protocol
• PostHog Adapter - Send logs to PostHog
• Custom Adapters - Build your own adapter