search

agorapulse / grails-sentry

A Sentry client for Grails
Apache License 2.0
12 stars 14 forks source link

readme

Sentry Grails Plugin

Build Status Download

Introduction

Sentry plugin provides a Grails client for integrating apps with Sentry. Sentry is an event logging platform primarily focused on capturing and aggregating exceptions.

It uses the official Sentry.io client under the cover.

Installation

Declare the plugin dependency in the build.gradle file, as shown here:

dependencies {
    ...
    compile("org.grails.plugins:sentry:11.7.25")
    ...
}

Config

Add your Sentry DSN to your grails-app/conf/application.yml.

grails:
    plugin:
        sentry:
            dsn: https://{PUBLIC_KEY}:{SECRET_KEY}@app.getsentry.com/{PATH}{PROJECT_ID}

The DSN can be found in project's Settings under Client Keys (DSN) section.

The plugin will sent notifications to Sentry by default, if you want to disable notifications for an specific environment set the active option as false.

environments:
    development:
        grails:
            plugin:
                sentry:
                    active: false
    test:
        grails:
            plugin:
                sentry:
                    active: false

You can also configure the multiple logger to which you want to append the sentry appender. You can also set the server name, but it is recommended to don't set this configuration and let the plugin to resolve it.

Optional configurations

# Not tested on Grails 3 plugin...
grails:
    plugin:
        sentry:
            dsn: https://foo:bar@api.sentry.io/123
            loggers: [LOGGER1, LOGGER2, LOGGER3]
            environment: staging
            serverName: dev.server.com
            levels: [ERROR]
            tags: {tag1: val1,  tag2: val2, tag3: val3}
            subsystems: 
                MODULE1: [com.company.services.module1, com.company.controllers.module1]
                MODULE2: [com.company.services.module2, com.company.controllers.module2]
                MODULE3: [com.company.services.module3, com.company.controllers.module3]
            logClassName: true
            logHttpRequest: true
            disableMDCInsertingServletFilter: true
            springSecurityUser: true
            springSecurityUserProperties:
                id: 'id'
                email: 'emailAddress'
                username: 'login'
                data: # Additional properties to be retrieved from user details object and passed as extra properties to Sentry user interface.
                    - 'authorities'
            priorities: 
                HIGH: [java.lang, com.microsoft.sqlserver.jdbc.SQLServerException]
                MID: [com.company.exception]
                LOW: [java.io]

Check Sentry-java documentation to configure connection, protocol and async options in your DSN. If you are sending extra tags from the plugin for the exceptions, make sure to enable the corresponding tag on sentry tag settings for the particular project to see the tag as a filter on the exception stream on sentry.

Usage

Logback Appender

The Logback Appender is automatically configured by the plugin, you just have to set enabled environments as shown in Configuration section.

All application exceptions will be logged on sentry by the appender. The appender is configured to log just the ERROR and WARN levels. To log manually just use the log.error() method.

sentryClient

You also can use sentryClient to sent info messages to Sentry:

import io.sentry.SentryClient
import io.sentry.event.Event
import io.sentry.event.EventBuilder
import io.sentry.event.interfaces.ExceptionInterface

SentryClient sentryClient // To inject Spring bean raven client in your controllers or services

// Send simple message
sentryClient?.sendMessage("some message")

// Send exception
sentryClient?.sendException(new Exception("some exception"))

// Custom event
EventBuilder eventBuilder = new EventBuilder()
           .withMessage("This is a test")
           .withLevel(Event.Level.INFO)
           .withLogger(MyClass.class.name)

sentryClient?.sendEvent(eventBuilder.build())

Latest releases

Bugs

To report any bug, please use the project Issues section on GitHub.

Contributing

Please contribute using Github Flow. Create a branch, add commits, and open a pull request.

License

Copyright © 2016 Alan Rafael Fachini, authors, and contributors. All rights reserved.

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Maintained by

Agorapulse & Scentbird