Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software faster, so we can get back to enjoying technology. If you want to join us Check out our open positions

Sentry SDK for Clojure

A very thin wrapper around the official Java library for Sentry.

This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning. In general, all changes endeavour to be non-breaking (by moving to new names rather than by breaking existing names). COMMITS is an ever-increasing counter of commits since the beginning of this repository.

Usage

(require '[sentry-clj.core :as sentry])

; You can initialize Sentry manually by providing a DSN or use one of the
; other optional configuration options supplied as a map (see below).

(sentry/init! "https://public:[email protected]/1")

; Sending a simple message is easy...

(try
  (do-something-risky)
  (catch Exception e
    (sentry/send-event {:message "Something has gone wrong!"
                        :throwable e})))

If you want an interpolated message, you need to provide the full map, i.e.,

(try
  (do-something-risky)
  (catch Exception e
    (sentry/send-event {:message {:message "Something %s has gone %s!"
                                  :params ["foo" "bar"]}
                        :throwable e})))

Additional Initialisation Options

key	description	default
:enable-external-configuration	Enable loading configuration from the properties file, system properties or environment variables
:environment	Set the environment on which Sentry events will be logged, e.g., "production"	production
:debug	Enable SDK logging at the debug level	false
:release	All events are assigned to a particular release
:dist	Set the application distribution that will be sent with each event
:server-name	Set the server name that will be sent with each event
:shutdown-timeout-millis	Wait up to X milliseconds before shutdown if there are events to send	2000ms
:in-app-includes	A seqable collection (vector for example) containing package names to include when sending events
:in-app-excludes	A seqable collection (vector for example) containing package names to ignore when sending events
:ignored-exceptions-for-type	Set exceptions that will be filtered out before sending to Sentry (a set of Classnames as Strings)
:enable-uncaught-exception-handler	Enables the uncaught exception handler	true
:before-send-fn	A function (taking an event and a hint)
	The body of the function must not be lazy (i.e., don't use filter on its own!) and must return an event or nil
	If a nil is returned, the event will not be sent to Sentry
	More Information
:before-breadcrumb-fn	A function (taking a breadcrumb and a hint)
	The body of the function must not be lazy (i.e., don't use filter on its own!) and must return a breadcrumb or nil
	If a nil is returned, the breadcrumb will not be sent to Sentry
	More Information
:contexts	A map of key/value pairs to attach to every Event that is sent.
	More Information
:traces-sample-rate	Set a uniform sample rate(a number of between 0.0 and 1.0) for all transactions for tracing
:traces-sample-fn	A function (taking a custom sample context and a transaction context) enables you to control trace transactions
:logs-enabled	Enable Sentry structured logging integration	false
:before-send-log-fn	A function (taking a log event) to filter logs, or update them before they are sent to Sentry
:serialization-max-depth	Set to a lower number, i.e., 2, if you experience circular reference errors when sending events	5
:trace-options-requests	Set to enable or disable tracing of options requests.	true
:instrumenter	Sets instrumenter for tracing. (values - :sentry - for default Sentry instrumentation, :otel - OpenTelemetry instrumentation)	:sentry
:event-processors	A seqable collection (vector for example) containing instances of event processors (implementing io.sentry.EventProcessor)

Some examples:

Basic Initialisation (using defaults):

(sentry/init! "https://public:[email protected]/1")

Initialisation with additional options:

(sentry/init! "https://public:[email protected]/1" {:environment "staging" :debug true :release "[email protected]" :in-app-excludes ["foo.bar"])

(sentry/init! "https://public:[email protected]/1" {:before-send-fn (fn [event _] (when-not (= (.. event getMessage getMessage "foo")) event))})

(sentry/init! "https://public:[email protected]/1" {:before-send-fn (fn [event _] (.setServerName event "fred") event)})

(sentry/init! "https://public:[email protected]/1" {:contexts {:foo "bar" :baz "wibble"}})

(sentry/init! "http://abcdefg@localhost:19000/2" {:logs-enabled true})

(sentry/init! "http://abcdefg@localhost:19000/2" {:logs-enabled true :before-send-log-fn (fn [logEvent] (.setBody logEvent "new message body") logEvent)})

Supported event keys

API Documentation

• :breadcrumbs - a collection of Breadcrumb maps. See below.
• :dist - a String which identifies the distribution.
• :environment - a String which identifies the environment.
• :event-id - a String id to use for the event. If not provided, one will be automatically generated.
• :extra - a map with Keyword or String keys (or anything for which clojure.core/name can be invoked) and values which can be JSON-ified. If :throwable is given, this will automatically include its ex-data.
  • note: :extra has been deprecated in favour of :contexts upon initialisation
• :fingerprints - a sequence of Strings that Sentry should use as a fingerprint.
• :level - a Keyword. One of :debug, :info, :warning, :error, :fatal. Probably most useful in conjunction with :message if you need to report an exceptional condition that's not an exception.
• :logger - a String which identifies the logger.
• :message - a map or String containing Message information. See below.
• :platform - a String which identifies the platform.
• :release - a String which identifies the release.
• :request - a map containing Request information. See below.
• :server-name - a String which identifies the server name.
• :tags - a map with Keyword or String keys (or anything for which clojure.core/name can be invoked) and values which can be coerced to Strings with clojure.core/str.
• :throwable - a Throwable object. Sentry's bread and butter.
• :transaction - a String which identifies the transaction.
• :user - a map containing User information. See below.

Breadcrumbs

API Documentation

When an event has a :breadcrumbs key, each element of the value collection should be a map. Each key is optional.

• :type - A String
• :level - a String
• :message - a String
• :category - a String
• :data - a map with String keys and String values
• :timestamp - a java.util.Date

Message

API Documentation

When an event has a :message key, either a simple string can be used, or if you require a parameterised message, the following data should be contained within a map, thus:

• :formatted - A String containing the fully formatted message. If missing, Sentry will try to interpolate the message.
• :message - An optional String containing the raw message. If there are params, it will be interpolated.
• :params - An optional sequence of String's containing parameters for interpolation, e.g., `["foo" "bar"]

User

API Documentation

When an event has a :user key, the data following should be contained within a map. You should provide at either the id or the ip-address.

• :email - A String
• :id - A String
• :username - A String
• :ip-address - A String
• :other - A map containing key/value pairs of Strings, i.e., {"a" "b" "c" "d"}

Request

API Documentation

When an event has a :request key, the data should be contained within a map. Each key is optional.

• :url - A String
• :method - A String
• :query-string - A String
• :data - An arbitrary value (e.g., a number, a string, a blob...)
• :cookies - A String
• :headers - A map containing key/value pairs of Strings, i.e., {"a" "b" "c" "d"}
• :env - A map containing key/value pairs of Strings, i.e., {"a" "b" "c" "d"}
• :other - A map containing key/value pairs of Strings, i.e., {"a" "b" "c" "d"}

Logs

API Documentation

Usage example

(require '[sentry-clj.core :as sentry])
(require '[sentry-clj.logging :as sentry-log])
(import '[io.sentry SentryInstantDate])

(sentry/init! "https://public:[email protected]/1" {:logs-enabled true})

; Sending some logs using log level specific functions 

(sentry-log/info "Test message")
(sentry-log/warn "Test message: %s" "TEST")

; Sending generic logs with additional parameters

(sentry-log/log :info {:request-id "24dbaef3-1d75-4304-8dde-e8cd47212591"} "Generic log")
(sentry-log/log :error {:operation "checkout"} "Generic %s log" "ERROR")
(sentry-log/log :warn (SentryInstantDate.) "Delayed processing detected at %s" (System/currentTimeMillis))

Log levels

Level-specific logging functions that provide a convenient way to log messages at specific levels. Each function accepts a message string and optional format arguments.

• trace - Log at trace level
• debug - Log at debug level
• info - Log at info level
• warn - Log at warning level
• error - Log at error level
• fatal - Log at fatal level

All level-specific functions accept the same parameters as (info message arg1 arg2):

• message - A String containing the log message, optionally with format placeholders
• & args - Optional format arguments for message interpolation

Generic log

The log function provides flexible logging with support for structured attributes and custom timestamps. It accepts a log level keyword followed by various argument combinations.

Parameters:

• level - A keyword specifying the log level (:trace, :debug, :info, :warn, :error, :fatal)
• data - Optional map of attributes or SentryDate, to add structured data to the log entry
• message - A String containing the log message, optionally with format placeholders
• & args - Optional format arguments for message interpolation

Using with Logback

API Documentation

If you are using Logback, you can add the Sentry appender to your logback configuration and include the io.sentry/sentry-logback {:mvn/version "RELEASE"} library in your deps.edn.

Two configuration approaches:

1. With sentry/init! in your application: If you initialize Sentry in your app using sentry/init!, you don't need to specify a DSN in the logback configuration.

<configuration scan="true" scanPeriod="5 seconds">
...
    <appender name="Sentry" class="io.sentry.logback.SentryAppender">
        <options>
            <sendDefaultPii>true</sendDefaultPii>
        </options>
        <!-- Optionally change minimum Event level. Default for Events is ERROR -->
        <minimumEventLevel>WARN</minimumEventLevel>
        <!-- Optionally change minimum Breadcrumbs level. Default for Breadcrumbs is INFO -->
        <minimumBreadcrumbLevel>DEBUG</minimumBreadcrumbLevel>
        <!-- Optionally change minimum Log level. Default for Log Events is INFO -->
        <minimumLevel>INFO</minimumLevel>
    </appender>
...
</configuration>

2. Standalone logback configuration: If you don't start Sentry in your app at all, you can add <dsn>${SENTRY_DSN}</dsn> and logs configuration to the Sentry appender options. Logs will be sent to Sentry automatically, and error logs will become error events.

<configuration scan="true" scanPeriod="5 seconds">
...
    <appender name="Sentry" class="io.sentry.logback.SentryAppender">
        <options>
            <dsn>${SENTRY_DSN}</dsn>
            <logs>
                <enabled>true</enabled>
            </logs>
            <sendDefaultPii>true</sendDefaultPii>
        </options>
    </appender>
...
</configuration>

License

Copyright © 2022 Coda Hale, Sentry

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.