Sentry Structured Logging for JavaScript (Browser/Node/Bun)

[AbhiPrasad]

Note: These instructions are now available in the Sentry docs - https://docs.sentry.io/product/explore/logs/getting-started/

Sentry is adding support for structured logs, so you can view and query your logs alongside your traces and errors—all in one place.

Note

To get early access to the Sentry logging product and to see how it works, see the announcement post.

To use the new Logging APIs to send application logs directly to Sentry, you'll have to upgrade to 9.12.0 of the JavaScript SDK or higher.

Logging is gated by an experimental option, _experiments.enableLogs.

Sentry.init({
  _experiments: {
    // Enable logs to be sent to Sentry.
    enableLogs: true,
  },
});

Then you can import and use methods from the Sentry.logger namespace to send logs to Sentry.

const { trace, debug, info, warn, error, fatal } = Sentry.logger;

trace('Starting database connection', { database: 'users' });
debug('Cache miss for user', { userId: 123 });
info('Updated profile', { profileId: 345 });
warn('Rate limit reached for endpoint', { endpoint: '/api/results/', isEnterprise: false });
error('Failed to process payment', { orderId: 'order_123', amount: 99.99 });
fatal('Database connection pool exhausted', { database: 'users', activeConnections: 100 });

You can leverage structured logging via the fmt helper. When you use fmt, the string template and parameters are sent separately so they can be queried independently in Sentry.

const { info, warn, fmt } = Sentry.logger;

info(fmt`Updated profile for user ${userId}`);
warn(fmt`Rate limit approaching for endpoint ${endpoint}. Requests: ${requests}, Limit: ${limit}`);

With server-side SDKs like @sentry/node, @sentry/bun or server-side of @sentry/nextjs or @sentry/sveltekit, you can do structured logging without needing the fmt helper function.

Sentry.logger.info('User %s logged in successfully', [123]);
Sentry.logger.warn('Failed to load user %s data', [123], { errorCode });

You can also configure the SDK to send logs via the JavaScript console object, using the SDK's consoleLoggingIntegration.

Sentry.init({
  // send console.log, console.error, and console.warn calls as logs to Sentry
  integrations: [Sentry.consoleLoggingIntegration({ levels: ['log', 'error', 'warn'] })],
});

In 9.13.0 and above of the JS SDK, we've added support to send logs via the winston logging library.

const winston = require('winston');
const Transport = require('winston-transport');

const SentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport);

const logger = winston.createLogger({
  transports: [new SentryWinstonTransport()],
});

To filter logs, or update them before they are sent to Sentry, you can use the _experiments.beforeSendLog option.

Supported SDKs:

• @sentry/astro
• @sentry/aws-serverless
• @sentry/browser
• @sentry/bun
• @sentry/core
• @sentry/cloudflare (9.16.0+)
• @sentry/ember
• @sentry/gatsby
• @sentry/google-cloud-serverless
• @sentry/nestjs
• @sentry/nextjs
• @sentry/node
• @sentry/nuxt
• @sentry/react
• @sentry/remix
• @sentry/solid
• @sentry/solidstart
• @sentry/svelte
• @sentry/sveltekit
• @sentry/vercel-edge (9.16.0+)
• @sentry/vue

Important

@sentry/deno currently does not have support for logging. This will be added in a future release of the SDK.

[zhiyan114]

There seems to be a typo with how fmt is used. The function is supposed to be called without a parenthesis. Ex: fmt`some ${format}`

[AbhiPrasad]

Good catch @zhiyan114 - fixed :)

[AbhiPrasad]

We’ve released 9.12.0 of the JS SDK which contains a variety of improvements and fixes for logging.

https://github.com/getsentry/sentry-javascript/releases/tag/9.12.0

We add a variety of new default attributes like server name for the backend sdks which should make debugging easier. We’ve also fixed a bug with how we were setting environment on logs.

For those who are using the node/bun sdks we’ve made improvements to the log buffering/flushing logic, which ensures we send logs more consistently and predictably.

Please upgrade and give it a try!

[AbhiPrasad]

We've released 9.13.0 of the JS SDK which contains support for the winston logging library.

const winston = require('winston');
const Transport = require('winston-transport');

const transport = Sentry.createSentryWinstonTransport(Transport);

const logger = winston.createLogger({
  transports: [transport],
});

https://github.com/getsentry/sentry-javascript/releases/tag/9.13.0

Please upgrade and give it a try!

[stefnnn]

Hey team Sentry. Promising product evolution for sure, we are eager to try to integrating our logs with our error reporting. We've been added to the pilot, upgraded to @sentry/nextjs@9.14.0 and @sentry/node@9.14.0 and added import * as Sentry from '@sentry/nextjs' to our central logging lib.

Now when we start the Next.js (15.2.3) frontend, we get an error Export logger doesn't exist in target module. I've traced this down to an import of Sentry.logger in our middleware.ts, where we log each incoming request. I'm slightly puzzled, as I assumed this code is only used server-side, but it looks like it's somehow imported into the clientside bundle at least in development.

Anything I should be trying differently? Here's a minimal repro: https://github.com/stefnnn/next-turbo-middleware

[stefnnn]

Thank you @AbhiPrasad, I've seen the release note and we already integrated the new version. Seems to work fine, now we are up to tuning our log usage. Thanks a bunch for the quick fix 🙌

[AbhiPrasad]

you might want to quickly upgrade to 9.16.1 - I released it as a patch fix right after. It contains some fixes for server-side flushing, so more logs make it to sentry (especially in serverless node and nextjs middleware).

[alexanderjulmer]

@AbhiPrasad, I updated to 9.16.1 and tried to add

  integrations: [
    Sentry.consoleLoggingIntegration({ levels: ["log", "error", "warn"] }),
  ],

to sentry.edge.config.ts when using it with Nextjs.

That results in this:

TypeError: An error occurred while loading instrumentation hook: g.consoleLoggingIntegration is not a function
    at 1900 (.next/server/edge-instrumentation.js:15:12650)
    at Function.t (.next/server/edge-runtime-webpack.js:1:495)
    at async Module.a (.next/server/edge-instrumentation.js:15:14229)
    at async u (.next/server/src/middleware.js:1:50632)
    at async ts (.next/server/src/middleware.js:13:32177)

I guess console logging doesn't work in the edge runtime?

[AbhiPrasad]

No it's because I forgot to export it as well 😓 - I opened #16228 to fix this.

For now you can import consoleLoggingIntegration from @sentry/core, which @sentry/nextjs depends on under the hood.

[AbhiPrasad]

Released a fix for this in https://github.com/getsentry/sentry-javascript/releases/tag/9.18.0

[alexanderjulmer]

It's quite likely me, but I cannot get the integration to log anything with "@sentry/nextjs": "^9.14.0" and "next": "^15.3.1".

I included logging in my sentry.server.config.ts:

Sentry.init({
  integrations: [Sentry.consoleLoggingIntegration({ levels: ["log", "error", "warn"] }) ],
  _experiments: { enableLogs: true },
})

Then I included the Logger on a page:

import * as Sentry from "@sentry/nextjs"
import { Dashboard } from "@/app/dashboard/components/Dashboard.tsx"

export default async function DashboardPage() {
  Sentry.logger.info("Rendering Dashboard")
  return <Dashboard />
}

[AbhiPrasad]

To help us debug further, could you add debug: true to your Sentry.init and share the logs? It would also be best if you created a GH issue (https://github.com/getsentry/sentry-javascript/issues) and added the debug output there, we'll get someone specifically assigned (probably me) to triage this and help fix whatever is going wrong. Thanks for reporting!

[alexanderjulmer]

It seems to work now, maybe I've been too impatient.

[hoi4]

Could this also be supported in @sentry/angular? At least createSentryWinstonTransport does not seem to exist in the latest version 9.14.0 🤔

[AbhiPrasad]

createSentryWinstonTransport is only available in the Node.js SDKs. I think winston is designed for only for Node.js because of it only has cjs support, and it depends on Node.js APIs.

All the other APIs should be available in @sentry/angular

[hoi4]

That makes sense, thank you!

[AbhiPrasad]

We've released 9.16.1 which makes some big improvements to how we flush logs in server-side environments (node, bun, google cloud functions, aws serverless, nextjs serverless, etc.) and adds logging support for Cloudflare Workers. Please upgrade and give it a try!

(note that 9.16.0 contains the Cloudflare features, but we recommend upgrading to 9.16.1 to get the flushing improvements)

[bangun-bcad]

@AbhiPrasad Is this feature only for SaaS version? I am using Self-Hosted Sentry but can not find explore logs menu on the sidebar

[AbhiPrasad]

@bangun-bcad because logs is in beta right now we have only turned the feature flags on for saas sentry. You can follow this GH issue to turn the feature flags on for your self-hosted instance: getsentry/self-hosted#3560, but we are not actively supporting this.

[GuusToussaint]

Any update on when this will be available for the @sentry/deno SDK?

[AbhiPrasad]

This is being tracked in #15988 - no timelines for this at the moment, but there is a workaround in that issue.