Sentry 2.2.0 Released!

Sentry 2.2.0 brings tracing, structured logs, metrics, browser feedback, and a handful of welcome fixes to your CFML and BoxLang applications. There’s quite a bit packed into this minor release!

And yes, it is a minor release. Your existing error reporting continues to work, and all of the new integrations are opt-in. You can upgrade for the bug fixes without turning on anything else.

Let’s get to the changes.

What’s New?

See where the time goes

Getting an exception into Sentry is helpful. But sometimes the problem is a request that takes five seconds and doesn’t throw an exception at all. Which query was slow? Did we miss the cache? Were we waiting on another service?

This release adds tracing for requests, queries, background jobs, CacheBox operations, and outbound HTTP calls. These spans give you a breakdown of the work happening inside a transaction.

You can enable request tracing in your ColdBox configuration:

moduleSettings.sentry = {
    DSN: getSystemSetting( "SENTRY_DSN", "" ),
    environment: "production",
    release: "my-app@1.0.0",
    enableRequestTracing: true,
    tracesSampleRate: 0.1
};

This example samples 10% of requests. Adjust that rate for your application’s traffic and your Sentry usage.

You can also wrap your own application code in a span:

sentry.withSpan( "load inventory", function( span ) {
    return loadInventory();
} );

Now that operation has a name and a duration in the trace. Much easier to investigate than “something in this handler is slow.”

Query tracing

Database queries are often a good place to start when tracking down a slow request. Sentry 2.2.0 adds query instrumentation through runtime listeners and compatible qb hooks, depending on your engine and installed versions.

For direct queries, you can use withQuerySpan:

result = sentry.withQuerySpan(
    sql,
    function( span ) {
        return queryExecute( sql, parameters, options );
    },
    "postgresql"
);

The wrapper records the query’s duration and status while preserving the callback’s result or exception. SQL literals are scrubbed, and bindings and result data aren’t collected.

The automatic integrations have some runtime requirements, so check the documentation before enabling them. The manual wrapper is useful wherever you need explicit coverage.

Background jobs, caches, and external calls

The work doesn’t always end when the request does.

Queue tracing can connect a job back to the request that scheduled it, with separate measurements for waiting and processing. Cache instrumentation records hits and misses without collecting the cached values. HTTP wrappers let you measure calls to other services and propagate trace headers to configured destinations.

These integrations help answer some very practical questions: are jobs spending their time waiting or working? Is the cache helping? Is our application slow, or is the service it calls slow?

Structured logs, metrics, and check-ins

There are also new APIs for structured logs and metrics:

• captureLog sends structured diagnostic messages.
• counter, gauge, and distribution record measurements.
• withMonitor reports check-ins for scheduled work.

For example, you can wrap an hourly task like this:

sentry.withMonitor(
    "hourly-work",
    function() {
        return performWork();
    },
    {
        schedule: {
            type: "interval",
            value: 1,
            unit: "hour"
        },
        checkin_margin: 2,
        max_runtime: 10
    }
);

This gives Sentry the schedule and matching check-ins for the work. Logs, metrics, and monitors have separate enablement settings, so you can choose which ones to add. Available monitor features depend on your Sentry plan.

Browser Feedback, Screenshots, and Replay

A bug report that says “it didn’t work” can leave you with a lot of questions. What page was the user on? What had they entered? What happened just before the problem?

The new browser companion adds a feedback widget with screenshots and session replay, along with browser tracing and supported Web Vitals.

The release includes built browser assets, so a plain CFML or BoxLang layout can use them without adding a Node build to the application. Bundler-based applications can use the included browser sources instead.

The widget supports keyboard and touch interaction, screenshot review and removal, and retries when delivery fails. Your application decides who is eligible to use it, which makes it possible to start with a small group of users.

There’s an important detail here: opening the feedback widget uploads the recent replay buffer. The message and screenshot are uploaded when the user submits the report. The widget explains that behavior to the user.

Capture uses conservative masking by default. If you want ordinary page content and form values to be readable, that requires an explicit capture policy. Review that policy for your application before enabling it.

Bug Fixes

There are several fixes for existing error reporting as well:

• Fixed a race where concurrent exception capture could access the Sentry singleton before initialization finished.
• Fixed timestamp generation so UTC ISO timestamps and epoch timestamps agree on CFML and native BoxLang.
• Improved stack-trace handling when a source file can’t be found.
• Made rewritten index.bxm URLs behave consistently with index.cfm URLs.

That last one came from a real report. The module already removed /index.cfm from rewritten request URLs, but it didn’t do the same for /index.bxm. A request for /foo/bar could therefore appear in Sentry as /index.bxm/foo/bar.

Now both root front controllers are handled consistently.

The release candidate also passed all 13 engine/framework CI combinations, browser tests and builds, and formatting checks.

Getting Started

Install Sentry 2.2.0 with CommandBox:

box install sentry@2.2.0

If you already use the module, your existing configuration can stay in place. Pick an integration that would help you understand your application and start there. There’s no need to turn everything on at once.

You can find configuration examples and integration requirements in the observability guide. As always, issues and pull requests are welcome. I’d love to hear what you’re using it for!