Sentry SDK

8.16.0.1

Sentry SDK🔗ℹ

1 Introduction🔗ℹ

This library provides an interface for capturing and sending errors to either a managed or a self-hosted Sentry instance.

2 Quickstart🔗ℹ

Install the package from the package server with

$ raco pkg install sentry

Call make-sentry to create an instance of the sentry client. Keep a reference to the client around for as long as your application needs to run and you can start sending exceptions by calling sentry-capture-exception!:

(require sentry)

(define client (make-sentry "https://key@sentry.io/12"))
(parameterize ([current-sentry client])
(sentry-capture-exception! (make-exn:fail "an error" (current-continuation-marks))))
(sentry-stop client)

3 Reference🔗ℹ

(require sentry)

package: sentry-lib

3.1 Core API🔗ℹ

procedure
(event? v) → boolean?
v : any/c

Returns #t when v is an event captured by sentry-capture-exception!.

Added in version 0.5 of package sentry-lib.

procedure
(sentry? v) → boolean?
v : any/c

Returns #t when v is a Sentry client.

parameter
(current-sentry) → (or/c #f sentry?)
(current-sentry client) → void?
client : (or/c #f sentry?)

Stores the current Sentry client for use with sentry-capture-exception!.

procedure
(make-sentry dsn
[ #:sampler sampler
#:backlog backlog
#:release release
#:environment environment
#:connect-timeout-ms connect-timeout
#:send-timeout-ms send-timeout
#:max-breadcrumbs max-breadcrumbs]) → sentry?
  dsn : string?
   sampler : (-> (or/c event? transaction?) (real-in 0.0 1.0))
= (lambda (_) 1.0)
  backlog : exact-positive-integer? = 128
   release : (or/c #f non-empty-string?)
= (getenv "SENTRY_RELEASE")
   environment : (or/c #f non-empty-string?)
= (getenv "SENTRY_ENVIRONMENT")
  connect-timeout : exact-positive-integer? = 5000
  send-timeout : exact-positive-integer? = 5000
  max-breadcrumbs : exact-positive-integer? = 50

Returns a Sentry client.

The #:backlog argument controls the size of the error queue. Events are dropped when the queue is full.

When the #:release argument is set, every event is tagged with the given value. Ditto for the #:environment argument.

The reutrned client logs messages to the 'sentry topic.

The #:sampler argument determines what chance an event has to be sent to the server. The default implementation samples 100% of all events.

Changed in version 0.5 of package sentry-lib: Added the #:sampler argument.

procedure
(sentry-capture-exception! e
[ client
#:level level
#:timestamp timestamp
#:server-name server-name
#:environment environment
#:release release
#:request request
#:tags tags
#:user user])
→ (evt/c void?)
  e : exn?
  client : (or/c #f sentry?) = (current-sentry)
  level : (or/c 'fatal 'error 'warning 'info 'debug) = 'error
  timestamp : (or/c date*? moment?) = (current-utc-date)
  server-name : (or/c #f non-empty-string?) = #f
  environment : (or/c #f non-empty-string?) = #f
  release : (or/c #f non-empty-string?) = #f
  request : (or/c #f request?) = #f
  tags : (hash/c non-empty-string? string?) = (hash)
  user : sentry-user? = (current-sentry-user)

Sends e to Sentry. Returns a synchronizable event that is ready for synchronization when the event leaves the queue, which means either that it has been sent to the Sentry API or that it has been dropped due to rate limits. When client is #f, all events are dropped.

procedure
(sentry-stop [client]) → void?
client : sentry? = (current-sentry)

Waits for all pending events in client to be sent and then shuts down its event loop.

3.2 Users🔗ℹ

procedure
(sentry-user? v) → boolean?
v : any/c

Returns #t when v represents a Sentry user.

parameter
(current-sentry-user) → (or/c #f sentry-user?)
(current-sentry-user user) → void?
user : (or/c #f sentry-user?)

A parameter that keeps track of data for the current user.

procedure
(make-sentry-user #:id id
[ #:username username
#:email email
#:ip-address ip-address
#:subscription subscription]) → sentry-user?
  id : non-empty-string?
  username : (or/c #f non-empty-string?) = #f
  email : (or/c #f non-empty-string?) = #f
  ip-address : (or/c #f non-empty-string?) = #f
  subscription : (or/c #f non-empty-string?) = #f

Creates an object that can store various bits of information about a user. These can then be passed to sentry-capture-exception! to have the data be associated with an error.

3.3 Tracing🔗ℹ

(require sentry/tracing)

package: sentry-lib

A transaction tracks a set of spans and delivers them to Sentry when the transaction completes. A span measures and records information about a block of code.

procedure
(transaction? v) → boolean?
v : any/c

Returns #t when v is a transaction.

parameter
(current-transaction) → (or/c #f transaction?)
(current-transaction t) → void?
t : (or/c #f transaction?)

Holds the current transaction. The call-with-transaction procedure automatically installs a transaction in this parameter.

procedure
(call-with-transaction name
proc
[ #:data data
#:source source
#:trace-id trace-id
#:parent-id parent-id
#:operation operation
#:description description]) → any
  name : string?
  proc : (-> transaction? any)
  data : (or/c #f (hash/c symbol? jsexpr?)) = #f
  source : symbol? = 'custom
  trace-id : (or/c #f string?) = #f
  parent-id : (or/c #f string?) = #f
  operation : symbol? = 'function
  description : (or/c #f string?) = #f

Calls proc in the context of a transaction with the given name. When the call to proc finishes executing, the transaction is sent to the current-sentry client. If there is no current client, the transaction information is discarded at the end of the call.

The value passed to the name argument should follow the conventions defined for the value passed to the #:source argument. The supported #:source values can be found in Sentry’s Transaction Annotations documentation.

The #:trace-id and #:parent-id may be used to propagate distributed tracing ids to the new transaction. See Sentry’s documentation on the sentry-trace header for details. If not provided, and the call is nested within another transaction, then the parent transaction’s values are inherited. If there is no parent transaction, then new trace and span ids are generated automatically.

The #:operation should be one of the values listed in Sentry’s Span Operations documentation.

The #:description may be an arbitrary string describing the transaction in detail.

procedure
(span? v) → boolean?
v : any/c

Returns #t when v is a span.

parameter
(current-span) → (or/c #f span?)
(current-span s) → void?
s : (or/c #f span?)

Holds the current span. The call-with-span procedure automatically installs a span in this parameter.

procedure
(call-with-span proc
[ #:operation operation
#:description description
#:origin origin
#:data data]) → any
  proc : (-> span? any)
  operation : symbol? = 'function
  description : (or/c #f string?) = #f
  origin : symbol? = 'manual
  data : (or/c #f (hash/c symbol? jsexpr?)) = #f

Calls proc in the context of a span with the given #:operation and #:description. When the call to proc finishes executing, the span is registered with the surrounding transaction. If there is no surrounding transaction, the span is discarded at the end of the call.

The #:operation should be one of the values listed in Sentry’s Span Operations documentation.

The #:description may be an arbitrary string describing the operation in detail.

procedure
(get-span-id v) → string?
v : (or/c span? transaction?)

Returns the id of the given transaction or span.

procedure
(get-trace-id v) → string?
v : (or/c span? transaction?)

Returns the trace id of the given transaction or span.

procedure
(span-set! s k v) → void?
  s : (or/c span? transaction?)
  k : symbol?
  v : jsexpr?

Sets k to v within s’s data payload.

3.3.1 Database Queries🔗ℹ

procedure
(trace-connection c) → connection?
c : connection?

Wraps all queries performed by c in a 'db.query span, recording the executed statement.