Skip to content

raven

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

raven

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
README.md
README.md
 
 
pom.xml
pom.xml
 
 

README.md

Raven (module)

Main module of the Raven project in java. It provides a client to send messages to a Sentry server as well as an implementation of an Handler for java.util.logging.

Installation

Maven

<dependency>
    <groupId>com.getsentry.raven</groupId>
    <artifactId>raven</artifactId>
    <version>7.3.0</version>
</dependency>

Other dependency managers

Details in the central Maven repository.

Manual dependency management

Relies on:

Usage (java.util.logging)

Configuration

In the logging.properties file set:

.level=WARN
handlers=com.getsentry.raven.jul.SentryHandler
com.getsentry.raven.jul.SentryHandler.dsn=https://publicKey:secretKey@host:port/1?options
#  Optional, provide tags 
com.getsentry.raven.jul.SentryHandler.tags=tag1:value1,tag2:value2
# Optional, provide release version of your application 
com.getsentry.raven.jul.SentryHandler.release=1.0.0
# Optional, override the server name (rather than looking it up dynamically)
com.getsentry.raven.jul.SentryHandler.serverName=server1
# Optional, select the ravenFactory class 
com.getsentry.raven.jul.SentryHandler.ravenFactory=com.getsentry.raven.DefaultRavenFactory

When starting your application, add the java.util.logging.config.file to the system properties, with the full path to the logging.properties as its value.

$ java -Djava.util.logging.config.file=/path/to/app.properties MyClass

In practice

import java.util.logging.Level;
import java.util.logging.Logger;

public class MyClass {
    private static final Logger logger = Logger.getLogger(MyClass.class.getName());

    void logSimpleMessage() {
        // This adds a simple message to the logs
        logger.log(Level.INFO, "This is a test");
    }

    void logException() {
        try {
            unsafeMethod();
        } catch (Exception e) {
            // This adds an exception to the logs
            logger.log(Level.SEVERE, "Exception caught", e);
        }
    }

    void unsafeMethod() {
        throw new UnsupportedOperationException("You shouldn't call that");
    }
}

Unsupported features

java.util.logging does not support either MDC nor NDC, meaning that it is not possible to attach additional/custom context values to the logs. In other terms, it is not possible to use the "extra" field supported by Sentry.

Manual usage (NOT RECOMMENDED)

It is possible to use the client manually rather than using a logging framework in order to send messages to Sentry. It is not recommended to use this solution as the API is more verbose and requires the developer to specify the value of each field sent to Sentry.

In practice

import com.getsentry.raven.Raven;
import com.getsentry.raven.RavenFactory;


public class MyClass {
    private static Raven raven;

    public static void main(String... args) {
        // Creation of the client with a specific DSN
        String dsn = args[0];
        raven = RavenFactory.ravenInstance(dsn);

        // It is also possible to use the DSN detection system like this
        raven = RavenFactory.ravenInstance();
    }

    void logSimpleMessage() {
        // This adds a simple message to the logs
        raven.sendMessage("This is a test");
    }

    void logException() {
        try {
            unsafeMethod();
        } catch (Exception e) {
            // This adds an exception to the logs
            raven.sendException(e);
        }
    }

    void unsafeMethod() {
        throw new UnsupportedOperationException("You shouldn't call that");
    }
}

In practice (advanced)

For more complex messages, it will be necessary to build an Event with the EventBuilder class.

import com.getsentry.raven.Raven;
import com.getsentry.raven.RavenFactory;
import com.getsentry.raven.event.Event;
import com.getsentry.raven.event.EventBuilder;
import com.getsentry.raven.event.interfaces.ExceptionInterface;
import com.getsentry.raven.event.interfaces.MessageInterface;

public class MyClass {
    private static Raven raven;

    public static void main(String... args) {
        // Creation of the client with a specific DSN
        String dsn = args[0];
        raven = RavenFactory.ravenInstance(dsn);

        // It is also possible to use the DSN detection system like this
        raven = RavenFactory.ravenInstance();

        // Advanced: To specify the ravenFactory used
        raven = RavenFactory.ravenInstance(new Dsn(dsn), "com.getsentry.raven.DefaultRavenFactory");
    }

    void logSimpleMessage() {
        // This adds a simple message to the logs
        EventBuilder eventBuilder = new EventBuilder()
                        .withMessage("This is a test")
                        .withLevel(Event.Level.INFO)
                        .withLogger(MyClass.class.getName());
        raven.runBuilderHelpers(eventBuilder); // Optional
        raven.sendEvent(eventBuilder.build());
    }

    void logException() {
        try {
            unsafeMethod();
        } catch (Exception e) {
            // This adds an exception to the logs
            EventBuilder eventBuilder = new EventBuilder()
                            .withMessage("Exception caught")
                            .withLevel(Event.Level.ERROR)
                            .withLogger(MyClass.class.getName())
                            .withSentryInterface(new ExceptionInterface(e));
            raven.runBuilderHelpers(eventBuilder); // Optional
            raven.sendEvent(eventBuilder.build());
        }
    }

    void unsafeMethod() {
        throw new UnsupportedOperationException("You shouldn't call that");
    }
}

This gives more control over the content of the Event and gives access to the complete API supported by Sentry.