diff --git a/README.md b/README.md index b3d0e88ad3..f232acc3a3 100644 --- a/README.md +++ b/README.md @@ -1,380 +1,18 @@ -# Raven +# raven-java -[![Build Status](https://travis-ci.org/getsentry/raven-java.svg?branch=master)](https://travis-ci.org/getsentry/raven-java) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.getsentry.raven/raven-all/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.getsentry.raven/raven-all) +Raven is the Java SDK for [Sentry](https://sentry.io/). It provides out-of-the-box support for +many popular JVM based frameworks and libraries, including Android, Log4j, Logback, and more. -Raven is the Java client for [Sentry](https://www.getsentry.com/). -Raven relies on the most popular logging libraries to capture and convert logs -before sending details to a Sentry instance. +In most cases using one of the existing integrations is preferred, but Raven additionally provides +a low level client for manually building and sending events to Sentry that can be used in any JVM +based application. - - [`java.util.logging`](http://docs.oracle.com/javase/7/docs/technotes/guides/logging/index.html) - support is provided by the main project [raven](raven) - - [log4j](https://logging.apache.org/log4j/1.2/) support is provided in [raven-log4j](raven-log4j) - - [log4j2](https://logging.apache.org/log4j/2.x/) can be used with [raven-log4j2](raven-log4j2) - - [logback](http://logback.qos.ch/) support is provided in [raven-logback](raven-logback) +## Resources -While it's **strongly recommended to use one of the supported logging -frameworks** to capture and send messages to Sentry, it is also possible to do so -manually with the main project [raven](raven). +* [Documentation](https://docs.sentry.io/clients/java/) +* [Bug Tracker](http://github.com/getsentry/raven-java/issues) +* [Code](http://github.com/getsentry/raven-java) +* [Mailing List](https://groups.google.com/group/getsentry) +* [IRC](irc://irc.freenode.net/sentry) (irc.freenode.net, #sentry) +* [Travis CI](http://travis-ci.org/getsentry/raven-java) -Raven supports both HTTP and HTTPS as transport protocols to the Sentry -instance. - -Support for [Google App Engine](https://appengine.google.com/) is provided in [raven-appengine](raven-appengine) - -## Maven -Stable versions of Raven are available on the -[central Maven Repository](https://search.maven.org) under the `com.getsentry` -groupId. (NOTE: This is change from the previous `net.kencochrane` groupId) - -Please see individual module `README`s for more information. - -### Snapshot versions -Newer (but less stable) versions (AKA snapshots) are available in Sonatype's -snapshot repository. - -To use it with maven, add the following repository: - -```xml - - sonatype-nexus-snapshots - Sonatype Nexus Snapshots - https://oss.sonatype.org/content/repositories/snapshots - - false - - - true - - -``` - -## Android -Raven also works on Android. For integration details, see the [raven-android README](https://github.com/getsentry/raven-java/blob/master/raven-android/README.md). - -## HTTP Request Context -If the runtime environment utilizes Servlets, events that are created during -the processing of an HTTP request will include additional contextual data about -that active request, such as the URL, method, parameters, and other data. (This -feature requires version 2.4 the Servlet API.) - -## Connection and protocol -It is possible to send events to Sentry over different protocols, depending -on the security and performance requirements. - -### HTTP -The most common way to send events to Sentry is via HTTP, this can be done by -using a DSN of this form: - - http://public:private@host:port/1 - -If not provided, the port will default to `80`. - -### HTTPS -It is possible to use an encrypted connection to Sentry via HTTPS: - - https://public:private@host:port/1 - -If not provided, the port will default to `443`. - -### HTTPS (naive) -If the certificate used over HTTPS is a wildcard certificate (which is not -handled by every version of Java), and the certificate isn't added to the -truststore, you can add a protocol setting to tell the client to be -naive and ignore hostname verification: - - naive+https://public:private@host:port/1 - -### Proxying HTTP(S) connections -If your application needs to send outbound requests through an HTTP proxy, -you can configure the proxy information via JVM networking properties or -as part of the Sentry DSN. - -For example, using JVM networking properties (affects the entire JVM process), - -``` -java \ - # if you are using the HTTP protocol \ - -Dhttp.proxyHost=proxy.example.com \ - -Dhttp.proxyPort=8080 \ - \ - # if you are using the HTTPS protocol \ - -Dhttps.proxyHost=proxy.example.com \ - -Dhttps.proxyPort=8080 \ - \ - # relevant to both HTTP and HTTPS - -Dhttp.nonProxyHosts=”localhost|host.example.com” \ - \ - MyApp -``` - -See [Java Networking and -Proxies](http://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html) -for more information about the proxy properties. - -Alternatively, using the Sentry DSN (only affects the Sentry HTTP client, -useful inside shared application containers), - - http://public:private@host:port/1?raven.http.proxy.host=proxy.example.com&raven.http.proxy.port=8080 - -## Options -It is possible to enable some options by adding data to the query string of the -DSN: - - http://public:private@host:port/1?option1=value1&option2&option3=value3 - -Some options do not require a value, just being declared signifies that the -option is enabled. - -### Async connection -In order to avoid performance issues due to a large amount of logs being -generated or a slow connection to the Sentry server, an asynchronous connection -is set up, using a low priority thread pool to submit events to Sentry. - -To disable the async mode, add `raven.async=false` to the DSN: - - http://public:private@host:port/1?raven.async=false - -#### Graceful Shutdown (advanced) -In order to shutdown the asynchronous connection gracefully, a `ShutdownHook` -is created. By default, the asynchronous connection is given 1 second -to shutdown gracefully, but this can be adjusted via -`raven.async.shutdowntimeout` (represented in milliseconds): - - http://public:private@host:port/1?raven.async.shutdowntimeout=5000 - -The special value `-1` can be used to disable the timeout and wait -indefinitely for the executor to terminate. - -The `ShutdownHook` could lead to memory leaks in an environment where -the life cycle of Raven doesn't match the life cycle of the JVM. - -An example would be in a JEE environment where the application using Raven -could be deployed and undeployed regularly. - -To avoid this behaviour, it is possible to disable the graceful shutdown. -This might lead to some log entries being lost if the log application -doesn't shut down the Raven instance nicely. - -The option to do so is `raven.async.gracefulshutdown`: - - http://public:private@host:port/1?raven.async.gracefulshutdown=false - -#### Queue size (advanced) -The default queue used to store unprocessed events is limited to 50 -items. Additional items added once the queue is full are dropped and -never sent to the Sentry server. -Depending on the environment (if the memory is sparse) it is important to be -able to control the size of that queue to avoid memory issues. - -It is possible to set a maximum with the option `raven.async.queuesize`: - - http://public:private@host:port/1?raven.async.queuesize=100 - -This means that if the connection to the Sentry server is down, only the 100 -most recent events will be stored and processed as soon as the server is back up. - -The special value `-1` can be used to enable an unlimited queue. Beware -that network connectivity or Sentry server issues could mean your process -will run out of memory. - -#### Threads count (advanced) -By default the thread pool used by the async connection contains one thread per -processor available to the JVM. - -It's possible to manually set the number of threads (for example if you want -only one thread) with the option `raven.async.threads`: - - http://public:private@host:port/1?raven.async.threads=1 - -#### Threads priority (advanced) -In most cases sending logs to Sentry isn't as important as an application -running smoothly, so the threads have a -[minimal priority](http://docs.oracle.com/javase/6/docs/api/java/lang/Thread.html#MIN_PRIORITY). - -It is possible to customise this value to increase the priority of those threads -with the option `raven.async.priority`: - - http://public:private@host:port/1?raven.async.priority=10 - -#### Graceful Shutdown (advanced) -In order to shutdown the buffer flushing thread gracefully, a `ShutdownHook` -is created. By default, the buffer flushing thread is given 1 second -to shutdown gracefully, but this can be adjusted via -`raven.buffer.shutdowntimeout` (represented in milliseconds): - - http://public:private@host:port/1?raven.buffer.shutdowntimeout=5000 - -The special value `-1` can be used to disable the timeout and wait -indefinitely for the executor to terminate. - -The `ShutdownHook` could lead to memory leaks in an environment where -the life cycle of Raven doesn't match the life cycle of the JVM. - -An example would be in a JEE environment where the application using Raven -could be deployed and undeployed regularly. - -To avoid this behaviour, it is possible to disable the graceful shutdown -by setting the `raven.buffer.gracefulshutdown` option: - - http://public:private@host:port/1?raven.buffer.gracefulshutdown=false - -### Buffering to disk upon network error -Raven can be configured to write events to a specified directory on disk -anytime communication with the Sentry server fails with the `raven.buffer.dir` -option. If the directory doesn't exist, Raven will attempt to create it -on startup and may therefore need write permission on the parent directory. -Raven always requires write permission on the buffer directory itself. - - http://public:private@host:port/1?raven.buffer.dir=raven-events - -The maximum number of events that will be stored on disk defaults to 50, -but can also be configured with the option `raven.buffer.size`: - - http://public:private@host:port/1?raven.buffer.size=100 - -If a buffer directory is provided, a background thread will periodically -attempt to re-send the events that are found on disk. By default it will -attempt to send events every 60 seconds. You can change this with the -`raven.buffer.flushtime` option (in milliseconds): - - http://public:private@host:port/1?raven.buffer.flushtime=10000 - -### Event sampling -Raven can be configured to sample events with the `raven.sample.rate` option: - - http://public:private@host:port/1?raven.sample.rate=0.75 - -This option takes a number from 0.0 to 1.0, representing the percent of -events to allow through to server (from 0% to 100%). By default all -events will be sent to the Sentry server. - -### Inapp classes -Sentry differentiate `in_app` stack frames (which are directly related to your application) -and the "not `in_app`" ones. -This difference is visible in the Sentry web interface where only the `in_app` -frames are displayed by default. - -#### Same frame as enclosing exception -Raven can use the `in_app` system to hide frames in the context of chained exceptions. - -Usually when a StackTrace is printed, the result looks like this: - - HighLevelException: MidLevelException: LowLevelException - at Main.a(Main.java:13) - at Main.main(Main.java:4) - Caused by: MidLevelException: LowLevelException - at Main.c(Main.java:23) - at Main.b(Main.java:17) - at Main.a(Main.java:11) - ... 1 more - Caused by: LowLevelException - at Main.e(Main.java:30) - at Main.d(Main.java:27) - at Main.c(Main.java:21) - ... 3 more - -Some frames are replaced by the `... N more` line as they are the same frames -as in the enclosing exception. - -To enable a similar behaviour from Raven use the `raven.stacktrace.hidecommon` option. - - http://public:private@host:port/1?raven.stacktrace.hidecommon - -#### Hide frames based on the class name -Raven can also mark some frames as `in_app` based on the name of the class. - -This can be used to hide parts of the stacktrace that are irrelevant to the problem -for example the stack frames in the `java.util` package will not help determining -what the problem was and will just create a longer stacktrace. - -Currently this is not configurable (see #49) and some packages are ignored by default: - -- `com.sun.*` -- `java.*` -- `javax.*` -- `org.omg.*` -- `sun.*` -- `junit.*` -- `com.intellij.rt.*` - -### Compression -By default the content sent to Sentry is compressed and encoded in base64 before -being sent. -However, compressing and encoding the data adds a small CPU and memory hit which -might not be useful if the connection to Sentry is fast and reliable. - -Depending on the limitations of the project (e.g. a mobile application with a -limited connection, Sentry hosted on an external network), it can be useful -to compress the data beforehand or not. - -It's possible to manually enable/disable the compression with the option -`raven.compression` - - http://public:private@host:port/1?raven.compression=false - -### Max message size -By default only the first 1000 characters of a message will be sent to -the server. This can be changed with the `raven.maxmessagelength` option. - - http://public:private@host:port/1?raven.maxmessagelength=1500 - -### Timeout (advanced) -A timeout is set to avoid blocking Raven threads because establishing a -connection is taking too long. - -It's possible to manually set the timeout length with `raven.timeout` -(in milliseconds): - - http://public:private@host:port/1?raven.timeout=10000 - -## Custom RavenFactory -At times, you may require custom functionality that is not included in `raven-java` -already. The most common way to do this is to create your own RavenFactory instance -as seen in the example below. - -```java -public class MyRavenFactory extends DefaultRavenFactory { - - @Override - public Raven createRavenInstance(Dsn dsn) { - Raven raven = new Raven(); - raven.setConnection(createConnection(dsn)); - - /* - Create and use the ForwardedAddressResolver, which will use the - X-FORWARDED-FOR header for the remote address if it exists. - */ - ForwardedAddressResolver forwardedAddressResolver = new ForwardedAddressResolver(); - raven.addBuilderHelper(new HttpEventBuilderHelper(forwardedAddressResolver)); - - return raven; - } - -} -``` - -### Registration -Next, you'll need to make your class known to Raven in one of two ways. - -#### Java ServiceLoader provider (recommended) -You'll need to add a `ServiceLoader` provider file to your project at -`src/main/resources/META-INF/services/com.getsentry.raven.RavenFactory` that contains -the name of your class so that it will be considered as a candidate `RavenFactory`. For an example, see -[how we configure the DefaultRavenFactory itself](https://github.com/getsentry/raven-java/blob/master/raven/src/main/resources/META-INF/services/com.getsentry.raven.RavenFactory). - -#### Manual registration -You can also manually register your `RavenFactory` instance. Note that this should be done -early in your application lifecycle so that your factory is available the first time -you attempt to send an event to the Sentry server. -```java -class MyApp { - public static void main(String[] args) { - RavenFactory.registerFactory(new MyRavenFactory()); - // ... your app code ... - } -} -``` - -### Configuration -Finally, see the `README` for the logger integration you use to find out how to -configure it to use your custom `RavenFactory`. diff --git a/docs/config.rst b/docs/config.rst index 59738eb8a3..607cd5433f 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -1,205 +1,432 @@ Configuration ============= -Raven's configuration happens via the DSN value. This guides you through -the configuration that applies generally and configuration that is -specific to the Java client. +**Note:** Raven's library and framework integration documentation explains how to to do +basic Raven configuration for each of the supported integrations. The configuration +below is typically for more advanced use cases and can be used in combination any of the other +integrations *once you set Raven up with the integration*. Please check the integration +documentation before you attempt to do any advanced configuration. -Connection and Protocols ------------------------- +Most of Raven's advanced configuration happens by setting options in your DSN, as seen below. -It is possible to send events to Sentry over different protocols, -depending on the security and performance requirements. +Connection and Protocol +----------------------- -HTTP -```` - -The most common way send events to Sentry is through HTTP, this can be -done by using a DSN of this form:: +It is possible to send events to Sentry over different protocols, depending +on the security and performance requirements. - http://:@sentryserver/ +HTTPS +~~~~~ -This is unavailable for Hosted Sentry which requires HTTPS. +The most common way to send events to Sentry is via HTTPS, this can be done by +using a DSN of this form: -HTTPS -````` +:: -It is possible to use an encrypted connection to Sentry using HTTPS:: + https://public:private@host:port/1 - ___DSN___ +If not provided, the port will default to ``443``. HTTPS (naive) -````````````` +~~~~~~~~~~~~~ If the certificate used over HTTPS is a wildcard certificate (which is not handled by every version of Java), and the certificate isn't added to the -truststore, it is possible to add a protocol setting to tell the client to -be naive and ignore the hostname verification:: +truststore, you can add a protocol setting to tell the client to be +naive and ignore hostname verification: + +:: + + naive+https://public:private@host:port/1 + +HTTP +~~~~ + +It is possible to use an unencrypted connection to Sentry via HTTP: + +:: + + http://public:private@host:port/1 + +If not provided, the port will default to ``80``. - naive+___DSN___ +Using a Proxy +~~~~~~~~~~~~~ + +If your application needs to send outbound requests through an HTTP proxy, +you can configure the proxy information via JVM networking properties or +as part of the Sentry DSN. + +For example, using JVM networking properties (affects the entire JVM process), + +:: + + java \ + # if you are using the HTTP protocol \ + -Dhttp.proxyHost=proxy.example.com \ + -Dhttp.proxyPort=8080 \ + \ + # if you are using the HTTPS protocol \ + -Dhttps.proxyHost=proxy.example.com \ + -Dhttps.proxyPort=8080 \ + \ + # relevant to both HTTP and HTTPS + -Dhttp.nonProxyHosts=”localhost|host.example.com” \ + \ + MyApp + +See `Java Networking and +Proxies `_ +for more information about the proxy properties. + +Alternatively, using the Sentry DSN (only affects the Sentry HTTP client, +useful inside shared application containers), + +:: + + http://public:private@host:port/1?raven.http.proxy.host=proxy.example.com&raven.http.proxy.port=8080 Options ------- -It is possible to enable some options by adding data to the query string -of the DSN:: +It is possible to enable some options by adding data to the query string of the +DSN: - ___DSN___?option1=value1&option2&option3=value3 +:: -Some options do not require a value, just being declared signifies that -the option is enabled. + http://public:private@host:port/1?option1=value1&option2&option3=value3 -Async Settings -`````````````` +Some options do not require a value, just being declared signifies that the +option is enabled. -Async connection: - In order to avoid performance issues due to a large amount of logs - being generated or a slow connection to the Sentry server, an - asynchronous connection is set up, using a low priority thread pool to - submit events to Sentry. +Async Connection +~~~~~~~~~~~~~~~~ - To disable the async mode, add ``raven.async=false`` to the DSN:: +In order to avoid performance issues due to a large amount of logs being +generated or a slow connection to the Sentry server, an asynchronous connection +is set up, using a low priority thread pool to submit events to Sentry. - ___DSN___?raven.async=false +To disable the async mode, add ``raven.async=false`` to the DSN: -Graceful Shutdown (advanced): - In order to shutdown the asynchronous connection gracefully, a - ``ShutdownHook`` is created. This could lead to memory leaks in an - environment where the life cycle of Raven doesn't match the life cycle - of the JVM. +:: - An example would be in a JEE environment where the application using - Raven could be deployed and undeployed regularly. + http://public:private@host:port/1?raven.async=false - To avoid this behaviour, it is possible to disable the graceful - shutdown. This might lead to some log entries being lost if the log - application doesn't shut down the Raven instance nicely. +Graceful Shutdown (Advanced) +```````````````````````````` - The option to do so is ``raven.async.gracefulshutdown``:: +In order to shutdown the asynchronous connection gracefully, a ``ShutdownHook`` +is created. By default, the asynchronous connection is given 1 second +to shutdown gracefully, but this can be adjusted via +``raven.async.shutdowntimeout`` (represented in milliseconds): - ___DSN___?raven.async.gracefulshutdown=false +:: -Queue and Thread Settings -````````````````````````` + http://public:private@host:port/1?raven.async.shutdowntimeout=5000 -Queue size (advanced): - The default queue used to store unprocessed events is limited to 50 - items. Additional items added once the queue is full are dropped and - never sent to the Sentry server. Depending on the environment (if the - memory is sparse) it is important to be able to control the size of - that queue to avoid memory issues. +The special value ``-1`` can be used to disable the timeout and wait +indefinitely for the executor to terminate. - It is possible to set a maximum with the option ``raven.async.queuesize``:: +The ``ShutdownHook`` could lead to memory leaks in an environment where +the life cycle of Raven doesn't match the life cycle of the JVM. - ___DSN___?raven.async.queuesize=100 +An example would be in a JEE environment where the application using Raven +could be deployed and undeployed regularly. - This means that if the connection to the Sentry server is down, only - the 100 most recent events will be stored and processed as soon as the - server is back up. +To avoid this behaviour, it is possible to disable the graceful shutdown. +This might lead to some log entries being lost if the log application +doesn't shut down the Raven instance nicely. - The special value ``-1`` can be used to enable an unlimited queue. Beware - that network connectivity or Sentry server issues could mean your process - will run out of memory. +The option to do so is ``raven.async.gracefulshutdown``: -Threads count (advanced): - By default the thread pool used by the async connection contains one - thread per processor available to the JVM (more threads wouldn't be - useful). +:: - It's possible to manually set the number of threads (for example if - you want only one thread) with the option ``raven.async.threads``:: + http://public:private@host:port/1?raven.async.gracefulshutdown=false - ___DSN___?raven.async.threads=1 +Queue Size (Advanced) +````````````````````` -Threads priority (advanced): - As in most cases sending logs to Sentry isn't as important as an - application running smoothly, the threads have a `minimal priority - `_. +The default queue used to store unprocessed events is limited to 50 +items. Additional items added once the queue is full are dropped and +never sent to the Sentry server. +Depending on the environment (if the memory is sparse) it is important to be +able to control the size of that queue to avoid memory issues. - It is possible to customise this value to increase the priority of - those threads with the option ``raven.async.priority``:: +It is possible to set a maximum with the option ``raven.async.queuesize``: - ___DSN___?raven.async.priority=10 +:: -Inapp Classes Settings -`````````````````````` + http://public:private@host:port/1?raven.async.queuesize=100 -Sentry differentiate ``in_app`` stack frames (which are directly related -to your application) and the "not ``in_app``" ones. This difference is -visible in the Sentry web interface where only the ``in_app`` frames are -displayed by default. +This means that if the connection to the Sentry server is down, only the 100 +most recent events will be stored and processed as soon as the server is back up. -Same frame as enclosing exception: - Raven can use the ``in_app`` system to hide frames in the context of - chained exceptions. +The special value ``-1`` can be used to enable an unlimited queue. Beware +that network connectivity or Sentry server issues could mean your process +will run out of memory. - Usually when a ``StackTrace`` is printed, the result looks like this:: +Threads Count (Advanced) +```````````````````````` - HighLevelException: MidLevelException: LowLevelException - at Main.a(Main.java:13) - at Main.main(Main.java:4) - Caused by: MidLevelException: LowLevelException - at Main.c(Main.java:23) - at Main.b(Main.java:17) - at Main.a(Main.java:11) - ... 1 more - Caused by: LowLevelException - at Main.e(Main.java:30) - at Main.d(Main.java:27) - at Main.c(Main.java:21) - ... 3 more +By default the thread pool used by the async connection contains one thread per +processor available to the JVM. - Some frames are replaced by the ... N more line as they are the same - frames as in the enclosing exception. +It's possible to manually set the number of threads (for example if you want +only one thread) with the option ``raven.async.threads``: - To enable a similar behaviour from raven use the - ``raven.stacktrace.hidecommon`` option:: +:: - ___DSN___?raven.stacktrace.hidecommon + http://public:private@host:port/1?raven.async.threads=1 -Hide frames based on the class name: - Raven can also mark some frames as ``in_app`` based on the name of the - class. +Threads Priority (Advanced) +``````````````````````````` - This can be used to hide parts of the stacktrace that are irrelevant - to the problem for example the stack frames in the ``java.util`` - package will not help determining what the problem was and will just - create a longer stacktrace. +In most cases sending logs to Sentry isn't as important as an application +running smoothly, so the threads have a +`minimal priority `_. - Currently this is not configurable and some packages are ignored by default: +It is possible to customise this value to increase the priority of those threads +with the option ``raven.async.priority``: - * com.sun.* - * java.* - * javax.* - * org.omg.* - * sun.* - * junit.* - * com.intellij.rt.* +:: -Transmission Settings -````````````````````` + http://public:private@host:port/1?raven.async.priority=10 + +Graceful Shutdown (Advanced) +```````````````````````````` + +In order to shutdown the buffer flushing thread gracefully, a ``ShutdownHook`` +is created. By default, the buffer flushing thread is given 1 second +to shutdown gracefully, but this can be adjusted via +``raven.buffer.shutdowntimeout`` (represented in milliseconds): + +:: + + http://public:private@host:port/1?raven.buffer.shutdowntimeout=5000 + +The special value ``-1`` can be used to disable the timeout and wait +indefinitely for the executor to terminate. + +The ``ShutdownHook`` could lead to memory leaks in an environment where +the life cycle of Raven doesn't match the life cycle of the JVM. + +An example would be in a JEE environment where the application using Raven +could be deployed and undeployed regularly. + +To avoid this behaviour, it is possible to disable the graceful shutdown +by setting the ``raven.buffer.gracefulshutdown`` option: + +:: + + http://public:private@host:port/1?raven.buffer.gracefulshutdown=false + +Buffering Events to Disk +~~~~~~~~~~~~~~~~~~~~~~~~ + +Raven can be configured to write events to a specified directory on disk +anytime communication with the Sentry server fails with the ``raven.buffer.dir`` +option. If the directory doesn't exist, Raven will attempt to create it +on startup and may therefore need write permission on the parent directory. +Raven always requires write permission on the buffer directory itself. + +:: + + http://public:private@host:port/1?raven.buffer.dir=raven-events + +The maximum number of events that will be stored on disk defaults to 50, +but can also be configured with the option ``raven.buffer.size``: + +:: + + http://public:private@host:port/1?raven.buffer.size=100 + +If a buffer directory is provided, a background thread will periodically +attempt to re-send the events that are found on disk. By default it will +attempt to send events every 60 seconds. You can change this with the +``raven.buffer.flushtime`` option (in milliseconds): + +:: + + http://public:private@host:port/1?raven.buffer.flushtime=10000 + +Event Sampling +~~~~~~~~~~~~~~ + +Raven can be configured to sample events with the ``raven.sample.rate`` option: + +:: + + http://public:private@host:port/1?raven.sample.rate=0.75 -Compression: - By default the content sent to Sentry is compressed and encoded in - base64 before being sent. This operation allows to send a smaller - amount of data for each event. However compressing and encoding the - data adds a CPU and memory overhead which might not be useful if the - connection to Sentry is fast and reliable. +This option takes a number from 0.0 to 1.0, representing the percent of +events to allow through to server (from 0% to 100%). By default all +events will be sent to the Sentry server. - Depending on the limitations of the project (ie: a mobile application - with a limited connection, Sentry hosted on an external network), it - can be interesting to compress the data beforehand or not. +Inapp Classes +~~~~~~~~~~~~~ - It's possible to manually enable/disable the compression with the - option ``raven.compression``:: +Sentry differentiate ``in_app`` stack frames (which are directly related to your application) +and the "not ``in_app``" ones. +This difference is visible in the Sentry web interface where only the ``in_app`` +frames are displayed by default. - ___DSN___?raven.compression=false +Same Frame as Enclosing Exception +````````````````````````````````` -Timeout (advanced): - To avoid blocking the thread because of a connection taking too much - time, a timeout can be set by the connection. +Raven can use the ``in_app`` system to hide frames in the context of chained exceptions. - By default the connection will set up its own timeout, but it's - possible to manually set one with ``raven.timeout`` (in milliseconds):: +Usually when a StackTrace is printed, the result looks like this: + +:: + + HighLevelException: MidLevelException: LowLevelException + at Main.a(Main.java:13) + at Main.main(Main.java:4) + Caused by: MidLevelException: LowLevelException + at Main.c(Main.java:23) + at Main.b(Main.java:17) + at Main.a(Main.java:11) + ... 1 more + Caused by: LowLevelException + at Main.e(Main.java:30) + at Main.d(Main.java:27) + at Main.c(Main.java:21) + ... 3 more + +Some frames are replaced by the ``... N more`` line as they are the same frames +as in the enclosing exception. + +To enable a similar behaviour from Raven use the ``raven.stacktrace.hidecommon`` option. + +:: + + http://public:private@host:port/1?raven.stacktrace.hidecommon + +Hide Frames Based on the Class Name +``````````````````````````````````` + +Raven can also mark some frames as ``in_app`` based on the name of the class. + +This can be used to hide parts of the stacktrace that are irrelevant to the problem +for example the stack frames in the ``java.util`` package will not help determining +what the problem was and will just create a longer stacktrace. + +Currently this is not configurable and some packages are ignored by default: + +- ``com.sun.*`` +- ``java.*`` +- ``javax.*`` +- ``org.omg.*`` +- ``sun.*`` +- ``junit.*`` +- ``com.intellij.rt.*`` + +Compression +~~~~~~~~~~~ + +By default the content sent to Sentry is compressed and encoded in base64 before +being sent. +However, compressing and encoding the data adds a small CPU and memory hit which +might not be useful if the connection to Sentry is fast and reliable. + +Depending on the limitations of the project (e.g. a mobile application with a +limited connection, Sentry hosted on an external network), it can be useful +to compress the data beforehand or not. + +It's possible to manually enable/disable the compression with the option +``raven.compression`` + +:: + + http://public:private@host:port/1?raven.compression=false + +Max Message Size +~~~~~~~~~~~~~~~~ + +By default only the first 1000 characters of a message will be sent to +the server. This can be changed with the ``raven.maxmessagelength`` option. + +:: + + http://public:private@host:port/1?raven.maxmessagelength=1500 + +Timeout (Advanced) +~~~~~~~~~~~~~~~~~~ + +A timeout is set to avoid blocking Raven threads because establishing a +connection is taking too long. + +It's possible to manually set the timeout length with ``raven.timeout`` +(in milliseconds): + +:: + + http://public:private@host:port/1?raven.timeout=10000 + +Custom RavenFactory +------------------- + +At times, you may require custom functionality that is not included in ``raven-java`` +already. The most common way to do this is to create your own ``RavenFactory`` instance +as seen in the example below. Note that you'll also need to register it with Raven and +possibly configure your integration to use it, as shown below. + +Implementation +~~~~~~~~~~~~~~ + +.. sourcecode:: java + + public class MyRavenFactory extends DefaultRavenFactory { + + @Override + public Raven createRavenInstance(Dsn dsn) { + Raven raven = new Raven(); + raven.setConnection(createConnection(dsn)); + + /* + Create and use the ForwardedAddressResolver, which will use the + X-FORWARDED-FOR header for the remote address if it exists. + */ + ForwardedAddressResolver forwardedAddressResolver = new ForwardedAddressResolver(); + raven.addBuilderHelper(new HttpEventBuilderHelper(forwardedAddressResolver)); + + return raven; + } + + } + +Next, you'll need to register your class with Raven in one of two ways. + +Registration +~~~~~~~~~~~~ + +Java ServiceLoader Provider (Recommended) +````````````````````````````````````````` + +You'll need to add a ``ServiceLoader`` provider file to your project at +``src/main/resources/META-INF/services/com.getsentry.raven.RavenFactory`` that contains +the name of your class so that it will be considered as a candidate ``RavenFactory``. For an example, see +`how we configure the DefaultRavenFactory itself `_. + +Manual Registration +``````````````````` + +You can also manually register your ``RavenFactory`` instance. If you are using +an integration that builds its own Raven client, such as a logging integration, this should +be done early in your application lifecycle so that your factory is available the first time +you attempt to send an event to the Sentry server. + +.. sourcecode:: java + + class MyApp { + public static void main(String[] args) { + RavenFactory.registerFactory(new MyRavenFactory()); + // ... your app code ... + } + } + +Configuration +~~~~~~~~~~~~~ - ___DSN___?raven.timeout=10000 +Finally, see the documentation for the integration you use to find out how to +configure it to use your custom ``RavenFactory``. diff --git a/docs/index.rst b/docs/index.rst index 46437f2699..dc990c3ab1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,6 @@ .. sentry:edition:: self - Raven-Java + Raven Java ========== .. sentry:edition:: on-premise, hosted @@ -10,23 +10,23 @@ Java ==== -Raven is the Java client for Sentry. Raven relies on the most popular -logging libraries to capture and convert logs before sending details to a -Sentry instance. - -While it's strongly recommended to use one of the supported logging -frameworks to capture and send messages to Sentry, a it is possible to do -so manually with the main project raven. +Raven for Java (``raven-java``) is the official Java client for Sentry. At its core it provides +a raw client for sending events to Sentry, but it is highly recommended that you +use one of the included library or framework integrations listed below if at all possible. .. toctree:: - :maxdepth: 2 - :titlesonly: + :maxdepth: 2 + :titlesonly: - installation - config - modules/index + config + usage + modules/index Resources: +* `Documentation `_ * `Bug Tracker `_ -* `Github Project `_ +* `Code `_ +* `Mailing List `_ +* `IRC `_ (irc.freenode.net, #sentry) +* `Travis CI `_ \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 99fc9fa963..0000000000 --- a/docs/installation.rst +++ /dev/null @@ -1,71 +0,0 @@ -Installation -============ - -When using Sentry with Java the strongly recommended way is to use one of -the supported logging framework integrations rather than the raw -"raven-java" clients. - -- `java.util.logging `_ - support is provided by the main project "raven-java" -- `log4j `_ support is provided in raven-log4j -- `log4j2 `_ can be used with raven-log4j2 -- `logback `_ support is provided in raven-logback - -Support for Google App Engine is provided in raven-appengine. - -Github ------- - -ALl modules are available on the `raven-java github project -`_. This includes raven-java -itself as well as all the logging integrations. - -Snapshot Versions ------------------ - -While the stable versions of raven are available on the central Maven -Repository, newer (but less stable) versions (AKA snapshots) are available -in Sonatype's snapshot repository. - -To use it with maven, add the following repository: - -.. sourcecode:: xml - - - sonatype-nexus-snapshots - Sonatype Nexus Snapshots - https://oss.sonatype.org/content/repositories/snapshots - - false - - - true - - - -Android -------- - -Raven works on Android, and relies on the `ServiceLoader -`_ -system which uses the content of ``META-INF/services``. This is used to -declare the ``RavenFactory`` implementations (to allow more control over -the automatically generated instances of ``Raven``) in -``META-INF/services/com.getsentry.raven.RavenFactory``. - -Unfortunately, when the APK is build, the content of ``META-INF/services`` of -the dependencies is lost, this prevent Raven to work properly. Solutions -exist for that problem: - -* Use `maven-android-plugin - `_ which has already - solved `this problem `_ -* Create manually a - ``META-INF/services/com.getsentry.raven.RavenFactory`` for the - project which will contain the canonical name of of implementation of - ``RavenFactory`` (ie. ``com.getsentry.raven.DefaultRavenFactory``). -* Register manually the ``RavenFactory`` when the application starts: - - .. sourcecode:: java - - RavenFactory.registerFactory(new DefaultRavenFactory()); diff --git a/docs/modules/android.rst b/docs/modules/android.rst new file mode 100644 index 0000000000..be7d3781ac --- /dev/null +++ b/docs/modules/android.rst @@ -0,0 +1,63 @@ +Android +======= + +Installation +------------ + +Using Gradle (Android Studio) in your ``app/build.gradle`` add: + +.. sourcecode:: groovy + + compile 'com.getsentry.raven:raven-android:7.8.2' + +For other dependency managers see the `central Maven repository `_. + +Usage +----- + +Configure your Sentry DSN (client key) in your ``AndroidManifest.xml``: + +.. sourcecode:: xml + + + + + +Your application must also have permission to access the internet in order to send +event to the Sentry server. In your ``AndroidManifest.xml``: + +.. sourcecode:: xml + + + + +Then, in your application's ``onCreate``, initialize the Raven client: + +.. sourcecode:: java + + import com.getsentry.raven.android.Raven; + + // "this" should be a reference to your main Activity + Raven.init(this.getApplicationContext()); + +Now you can use ``Raven`` to capture events anywhere in your application: + +.. sourcecode:: java + + // Send a simple event to the Sentry server + Raven.capture("Error message"); + + try { + something() + } catch (Exception e) { + // Send an exception event to the Sentry server + Raven.capture(e); + } + + // Or build an event manually + EventBuilder eventBuilder = new EventBuilder() + .withMessage("Exception caught") + .withLevel(Event.Level.ERROR); + Raven.capture(eventBuilder.build()); diff --git a/docs/modules/appengine.rst b/docs/modules/appengine.rst index 0108b53732..de7a7bf6c5 100644 --- a/docs/modules/appengine.rst +++ b/docs/modules/appengine.rst @@ -1,24 +1,17 @@ Google App Engine ================= -The `raven-appengine` module enables the support of the async connections -in Google App Engine. +The ``raven-appengine`` library provides `Google App Engine `_ +support for Raven via the `Task Queue API +`_. -The project can be found on github: `raven-java/appengine -`_ - -Google App Engine doesn't support threads but provides instead a -TaskQueueing system allowing tasks to be run in the background. - -This module replaces the async system provided by default with one relying -on the tasks. - -This module is not useful outside of Google App Engine. +The source can be found `on Github +`_. Installation ------------ -If you want to use Maven you can install Raven-AppEngine as dependency: +Using Maven: .. sourcecode:: xml @@ -28,17 +21,29 @@ If you want to use Maven you can install Raven-AppEngine as dependency: 7.8.2 +Using Gradle: + +.. sourcecode:: groovy + + compile 'com.getsentry.raven:raven-appengine:7.8.2' + +Using SBT: + +.. sourcecode:: scala + + libraryDependencies += "com.getsentry.raven" % "raven-appengine" % "7.8.2" + +For other dependency managers see the `central Maven repository `_. + Usage ----- -This module provides a new ``RavenFactory`` which replaces the default async -system with a GAE compatible one. +This module provides a new ``RavenFactory`` implementation which replaces the default async +system with a Google App Engine compatible one. You'll need to configure Raven to use the +``com.getsentry.raven.appengine.AppEngineRavenFactory`` as its factory. The queue size and thread options will not be used as they are specific to -the default multithreaded system. - -It is necessary to force the raven factory name to -``com.getsentry.raven.appengine.AppEngineRavenFactory``. +the default Java threading system. Queue Name ---------- @@ -46,7 +51,7 @@ Queue Name By default, the default task queue will be used, but it's possible to specify which one will be used with the ``raven.async.gae.queuename`` option:: - ___DSN___?raven.async.gae.queuename=MyQueueName + http://public:private@host:port/1?raven.async.gae.queuename=MyQueueName Connection Name --------------- @@ -55,7 +60,7 @@ As the queued tasks are sent across different instances of the application, it's important to be able to identify which connection should be used when processing the event. To do so, the GAE module will identify each connection based on an identifier either automatically generated or -user defined. TO manually set the connection identifier (only used -internally) use the option ``raven.async.connectionid``:: +user defined. To manually set the connection identifier (only used +internally) use the option ``raven.async.gae.connectionid``:: - ___DSN___?raven.async.gae.connectionid=MyConnection + http://public:private@host:port/1?raven.async.gae.connectionid=MyConnection diff --git a/docs/modules/index.rst b/docs/modules/index.rst index eb48f1f1ce..9cf4429544 100644 --- a/docs/modules/index.rst +++ b/docs/modules/index.rst @@ -1,8 +1,8 @@ -Modules -======= +Integrations +============ -Raven-Java comes in different modules from low-level access to event -submission as well as integration into different packages. +The Raven Java SDK comes with support for some frameworks and libraries so that +you don't have to capture and send errors manually. .. toctree:: :maxdepth: 1 @@ -12,3 +12,4 @@ submission as well as integration into different packages. log4j2 logback appengine + android diff --git a/docs/modules/log4j.rst b/docs/modules/log4j.rst index f1f0a0d12f..a29a306ca3 100644 --- a/docs/modules/log4j.rst +++ b/docs/modules/log4j.rst @@ -1,18 +1,18 @@ -Log4j -===== +Log4j 1.x +========= -Raven-Java provides `log4j `_ -support for Raven. It provides an `Appender +The ``raven-log4j`` library provides `Log4j 1.x `_ +support for Raven via an `Appender `_ -for log4j to send the logged events to Sentry. +that sends logged exceptions to Sentry. -The project can be found on github: `raven-java/raven-log4j -`_ +The source can be found `on Github +`_. Installation ------------ -If you want to use Maven you can install Raven-Log4j as dependency: +Using Maven: .. sourcecode:: xml @@ -22,50 +22,246 @@ If you want to use Maven you can install Raven-Log4j as dependency: 7.8.2 -If you manually want to manage your dependencies: +Using Gradle: -- :doc:`raven dependencies ` -- `log4j-1.2.17.jar `_ -- `slf4j-log4j12-1.7.7.jar - `_ - is recommended as the implementation of slf4j (instead of slf4j-jdk14). +.. sourcecode:: groovy + + compile 'com.getsentry.raven:raven-log4j:7.8.2' + +Using SBT: + +.. sourcecode:: scala + + libraryDependencies += "com.getsentry.raven" % "raven-log4j" % "7.8.2" + +For other dependency managers see the `central Maven repository `_. Usage ----- -The following configuration (``logging.properties``) gets you started for -logging with log4j and Sentry: +The following examples configure a ``ConsoleAppender`` that logs to standard out +at the ``INFO`` level and a ``SentryAppender`` that logs to the Sentry server at +the ``WARN`` level. The ``ConsoleAppender`` is only provided as an example of +a non-Sentry appender that is set to a different logging threshold, like one you +may already have in your project. + +Example configuration using the ``log4j.properties`` format: .. sourcecode:: ini - log4j.rootLogger=WARN, SentryAppender - log4j.appender.SentryAppender=com.getsentry.raven.log4j.SentryAppender - log4j.appender.SentryAppender.dsn=___DSN___ - log4j.appender.SentryAppender.tags=tag1:value1,tag2:value2 - # Optional, allows to select the ravenFactory - #log4j.appender.SentryAppender.ravenFactory=com.getsentry.raven.DefaultRavenFactory + # Enable the Console and Sentry appenders + log4j.rootLogger=INFO, Console, Sentry + + # Configure the Console appender + log4j.appender.Console=org.apache.log4j.ConsoleAppender + log4j.appender.Console.layout=org.apache.log4j.PatternLayout + log4j.appender.Console.layout.ConversionPattern=%d{HH:mm:ss.SSS} [%t] %-5p: %m%n + + # Configure the Sentry appender, overriding the logging threshold to the WARN level + log4j.appender.Sentry=com.getsentry.raven.log4j.SentryAppender + log4j.appender.Sentry.threshold=WARN -Alternatively in the ``log4j.xml`` file set: +Alternatively, using the ``log4j.xml`` format: .. sourcecode:: xml - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + +Next, **you'll need to configure your DSN** (client key) and optionally other values such as +``environment`` and ``release``. See below for the two ways you can do this. + +Configuration via Runtime Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the most flexible method for configuring the ``SentryAppender``, +because it can be easily changed based on the environment you run your +application in. + +The following can be set as System Environment variables: + +.. sourcecode:: shell + + SENTRY_EXAMPLE=xxx java -jar app.jar + +Or as Java System Properties: + +.. sourcecode:: shell + + java -Dsentry.example=xxx -jar app.jar -It's possible to add extra details to events captured by the Log4j module -thanks to both `the MDC +Configuration parameters follow: + +======================= ======================= =============================== =========== +Environment variable Java System Property Example value Description +======================= ======================= =============================== =========== +``SENTRY_DSN`` ``sentry.dsn`` ``https://host:port/1?options`` Your Sentry DSN (client key), if left blank Raven will no-op +``SENTRY_RELEASE`` ``sentry.release`` ``1.0.0`` Optional, provide release version of your application +``SENTRY_ENVIRONMENT`` ``sentry.environment`` ``production`` Optional, provide environment your application is running in +``SENTRY_SERVERNAME`` ``sentry.servername`` ``server1`` Optional, override the server name (rather than looking it up dynamically) +``SENTRY_RAVENFACTORY`` ``sentry.ravenfactory`` ``com.foo.RavenFactory`` Optional, select the ravenFactory class +``SENTRY_TAGS`` ``sentry.tags`` ``tag1:value1,tag2:value2`` Optional, provide tags +``SENTRY_EXTRA_TAGS`` ``sentry.extratags`` ``foo,bar,baz`` Optional, provide tag names to be extracted from MDC +======================= ======================= =============================== =========== + +Configuration via Static File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure everything statically within the ``log4j.properties`` or ``log4j.xml`` +file itself. This is less flexible and not recommended because it's more difficult to change +the values when you run your application in different environments. + +Example configuration in the ``log4j.properties`` file: + +.. sourcecode:: ini + + # Enable the Console and Sentry appenders + log4j.rootLogger=INFO, Console, Sentry + + # Configure the Console appender + log4j.appender.Console=org.apache.log4j.ConsoleAppender + log4j.appender.Console.layout=org.apache.log4j.PatternLayout + log4j.appender.Console.layout.ConversionPattern=%d{HH:mm:ss.SSS} [%t] %-5p: %m%n + + # Configure the Sentry appender, overriding the logging threshold to the WARN level + log4j.appender.Sentry=com.getsentry.raven.log4j.SentryAppender + log4j.appender.Sentry.threshold=WARN + + # Set the Sentry DSN + log4j.appender.Sentry.dsn=https://host:port/1?options + + # Optional, provide release version of your application + log4j.appender.Sentry.release=1.0.0 + + # Optional, provide environment your application is running in + log4j.appender.Sentry.environment=production + + # Optional, override the server name (rather than looking it up dynamically) + log4j.appender.Sentry.serverName=server1 + + # Optional, select the ravenFactory class + log4j.appender.Sentry.ravenFactory=com.foo.RavenFactory + + # Optional, provide tags + log4j.appender.Sentry.tags=tag1:value1,tag2:value2 + + # Optional, provide tag names to be extracted from MDC + log4j.appender.Sentry.extraTags=foo,bar,baz + +Alternatively, using the ``log4j.xml`` format: + +.. sourcecode:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Additional Data +--------------- + +It's possible to add extra data to events thanks to `the MDC `_ and `the NDC `_ -systems provided by Log4j are usable, allowing to attach extras -information to the event. +systems provided by Log4j 1.x. + +Mapped Tags +~~~~~~~~~~~ + +By default all MDC parameters are stored under the "Additional Data" tab in Sentry. By +specifying the ``extraTags`` parameter in your configuration file you can +choose which MDC keys to send as tags instead, which allows them to be used as +filters within the Sentry UI. + +.. sourcecode:: ini + + log4j.appender.SentryAppender.extraTags=Environment,OS + +.. sourcecode:: java + + void logWithExtras() { + // MDC extras + MDC.put("Environment", "Development"); + MDC.put("OS", "Linux"); + + // This sends an event where the Environment and OS MDC values are set as tags + logger.error("This is a test"); + } -Practical Example ------------------ +In Practice +----------- .. sourcecode:: java @@ -77,8 +273,8 @@ Practical Example private static final Logger logger = Logger.getLogger(MyClass.class); void logSimpleMessage() { - // This adds a simple message to the logs - logger.info("This is a test"); + // This sends a simple event to Sentry + logger.error("This is a test"); } void logWithExtras() { @@ -86,50 +282,27 @@ Practical Example MDC.put("extra_key", "extra_value"); // NDC extras are sent under 'log4J-NDC' NDC.push("Extra_details"); - // This adds a message with extras to the logs - logger.info("This is a test"); + // This sends an event with extra data to Sentry + logger.error("This is a test"); } void logException() { try { unsafeMethod(); } catch (Exception e) { - // This adds an exception to the logs + // This sends an exception event to Sentry logger.error("Exception caught", e); } } void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); + throw new UnsupportedOperationException("You shouldn't call this!"); } } -Mapped Tags ------------ - -By default all MDC parameters are sent under the Additional Data Tab. By -specify the ``extraTags`` parameter in your configuration file. You can -specify MDC keys to send as tags instead of including them in Additional -Data. This allows them to be filtered within Sentry. - -.. sourcecode:: java - - log4j.appender.SentryAppender.extraTags=Environment,OS - void logWithExtras() { - // MDC extras - MDC.put("Environment", "Development"); - MDC.put("OS", "Linux"); - - // This adds a message with extras and MDC keys declared in extraTags as tags to Sentry - logger.info("This is a test"); - } - Asynchronous Logging -------------------- -It is not recommended to attempt to set up ``SentryAppender`` within an -`AsyncAppender +Raven uses asynchronous communication by default, and so it is unnecessary +to use an `AsyncAppender `_. -While this is a common solution to avoid blocking the current thread until -the event is sent to Sentry, it is recommended to rely instead on the -asynchronous connection provided by Raven. diff --git a/docs/modules/log4j2.rst b/docs/modules/log4j2.rst index ea28817ba7..7402505020 100644 --- a/docs/modules/log4j2.rst +++ b/docs/modules/log4j2.rst @@ -1,18 +1,18 @@ -Log4j 2 -======= +Log4j 2.x +========= -Raven-Java provides `Log4j 2 `_ -support for Raven. It provides an `Appender +The ``raven-log4j2`` library provides `Log4j 2.x `_ +support for Raven via an `Appender `_ -for Log4j 2 to send the logged events to Sentry. +that sends logged exceptions to Sentry. -The project can be found on github: `raven-java/raven-log4j2 -`_ +The source can be found `on Github +`_. Installation ------------ -If you want to use Maven you can install Raven-Log4j2 as dependency: +Using Maven: .. sourcecode:: xml @@ -22,72 +22,157 @@ If you want to use Maven you can install Raven-Log4j2 as dependency: 7.8.2 -If you manually want to manage your dependencies: +Using Gradle: -- :doc:`raven dependencies ` -- `log4j-api-2.1.jar - `_ -- `log4j-core-2.0.jar - `_ -- `log4j-slf4j-impl-2.1.jar - `_ - is recommended as the implementation of slf4j (instead of slf4j-jdk14). +.. sourcecode:: groovy + + compile 'com.getsentry.raven:raven-log4j2:7.8.2' + +Using SBT: + +.. sourcecode:: scala + + libraryDependencies += "com.getsentry.raven" % "raven-log4j2" % "7.8.2" + +For other dependency managers see the `central Maven repository `_. Usage ----- -The following configuration (``log4j2.xml``) gets you started for -logging with log4j2 and Sentry: +The following example configures a ``ConsoleAppender`` that logs to standard out +at the ``INFO`` level and a ``SentryAppender`` that logs to the Sentry server at +the ``WARN`` level. The ``ConsoleAppender`` is only provided as an example of +a non-Sentry appender that is set to a different logging threshold, like one you +may already have in your project. -.. sourcecode:: java +Example configuration using the ``log4j2.xml`` format: + +.. sourcecode:: xml - - - - ___DSN___?options - - - tag1:value1,tag2:value2 - - - - - - - - - - - + + + + + + + + + + + + + + + -It's possible to add extra details to events captured by the Log4j 2 -module thanks to the `marker system -`_ which will -add a tag log4j2-Marker. Both the MDC and the NDC systems provided by -Log4j 2 are usable, allowing to attach extras information to the event. +Next, **you'll need to configure your DSN** (client key) and optionally other values such as +``environment`` and ``release``. See below for the two ways you can do this. + +Configuration via Runtime Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the most flexible method for configuring the ``SentryAppender``, +because it can be easily changed based on the environment you run your +application in. + +The following can be set as System Environment variables: + +.. sourcecode:: shell + + SENTRY_EXAMPLE=xxx java -jar app.jar + +Or as Java System Properties: + +.. sourcecode:: shell + + java -Dsentry.example=xxx -jar app.jar + +Configuration parameters follow: + +======================= ======================= =============================== =========== +Environment variable Java System Property Example value Description +======================= ======================= =============================== =========== +``SENTRY_DSN`` ``sentry.dsn`` ``https://host:port/1?options`` Your Sentry DSN (client key), if left blank Raven will no-op +``SENTRY_RELEASE`` ``sentry.release`` ``1.0.0`` Optional, provide release version of your application +``SENTRY_ENVIRONMENT`` ``sentry.environment`` ``production`` Optional, provide environment your application is running in +``SENTRY_SERVERNAME`` ``sentry.servername`` ``server1`` Optional, override the server name (rather than looking it up dynamically) +``SENTRY_RAVENFACTORY`` ``sentry.ravenfactory`` ``com.foo.RavenFactory`` Optional, select the ravenFactory class +``SENTRY_TAGS`` ``sentry.tags`` ``tag1:value1,tag2:value2`` Optional, provide tags +``SENTRY_EXTRA_TAGS`` ``sentry.extratags`` ``foo,bar,baz`` Optional, provide tag names to be extracted from MDC +======================= ======================= =============================== =========== + +Configuration via Static File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure everything statically within the ``log4j2.xml`` +file itself. This is less flexible and not recommended because it's more difficult to change +the values when you run your application in different environments. + +Example configuration in the ``log4j.properties`` file: + +.. sourcecode:: xml + + + + + + + + + + + https://host:port/1?options + + + 1.0.0 + + + production + + + server1 + + + com.foo.RavenFactory + + + tag1:value1,tag2:value2 + + + foo,bar,baz + + + + + + + + + + + + +Additional Data +--------------- + +It's possible to add extra data to events thanks to `the marker system +`_ +provided by Log4j 2.x. Mapped Tags ------------ +~~~~~~~~~~~ -By default all MDC parameters are sent under the Additional Data Tab. By -specify the ``extraTags`` parameter in your configuration file. You can -specify MDC keys to send as tags instead of including them in Additional -Data. This allows them to be filtered within Sentry. +By default all MDC parameters are stored under the "Additional Data" tab in Sentry. By +specifying the ``extraTags`` parameter in your configuration file you can +choose which MDC keys to send as tags instead, which allows them to be used as +filters within the Sentry UI. .. sourcecode:: xml - - Environment,OS - + Environment,OS .. sourcecode:: java @@ -96,12 +181,12 @@ Data. This allows them to be filtered within Sentry. MDC.put("Environment", "Development"); MDC.put("OS", "Linux"); - // This adds a message with extras and MDC keys declared in extraTags as tags to Sentry - logger.info("This is a test"); + // This sends an event where the Environment and OS MDC values are set as tags + logger.error("This is a test"); } -Practical Example ------------------ +In Practice +----------- .. sourcecode:: java @@ -115,13 +200,13 @@ Practical Example private static final Marker MARKER = MarkerManager.getMarker("myMarker"); void logSimpleMessage() { - // This adds a simple message to the logs - logger.info("This is a test"); + // This sends a simple event to Sentry + logger.error("This is a test"); } void logWithTag() { - // This adds a message with a tag to the logs named 'log4j2-Marker' - logger.info(MARKER, "This is a test"); + // This sends an event with a tag named 'log4j2-Marker' to Sentry + logger.error(MARKER, "This is a test"); } void logWithExtras() { @@ -129,20 +214,20 @@ Practical Example ThreadContext.put("extra_key", "extra_value"); // NDC extras are sent under 'log4j2-NDC' ThreadContext.push("Extra_details"); - // This adds a message with extras to the logs - logger.info("This is a test"); + // This sends an event with extra data to Sentry + logger.error("This is a test"); } void logException() { try { unsafeMethod(); } catch (Exception e) { - // This adds an exception to the logs + // This sends an exception event to Sentry logger.error("Exception caught", e); } } void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); + throw new UnsupportedOperationException("You shouldn't call this!"); } } diff --git a/docs/modules/logback.rst b/docs/modules/logback.rst index fd523d5e92..08cfd5ce0b 100644 --- a/docs/modules/logback.rst +++ b/docs/modules/logback.rst @@ -1,64 +1,181 @@ Logback ======= -Raven-Java provides `logback `_ -support for Raven. It provides an `Appender +The ``raven-logback`` library provides `Logback `_ +support for Raven via an `Appender `_ -for logback to send the logged events to Sentry. +that sends logged exceptions to Sentry. + +The source can be found `on Github +`_. Installation ------------ -If you want to use Maven you can install Raven-Logback as dependency: +Using Maven: .. sourcecode:: xml - com.getsentry.raven - raven-logback - 7.8.2 + com.getsentry.raven + raven-logback + 7.8.2 -- :doc:`raven dependencies ` -- `logback-core-1.1.2.jar - `_ -- `logback-classic-1.1.2.jar - `_ - will act as the implementation of slf4j (instead of slf4j-jdk14). +Using Gradle: + +.. sourcecode:: groovy + + compile 'com.getsentry.raven:raven-logback:7.8.2' + +Using SBT: + +.. sourcecode:: scala + + libraryDependencies += "com.getsentry.raven" % "raven-logback" % "7.8.2" + +For other dependency managers see the `central Maven repository `_. Usage ----- -In the ``logback.xml`` file set: +The following example configures a ``ConsoleAppender`` that logs to standard out +at the ``INFO`` level and a ``SentryAppender`` that logs to the Sentry server at +the ``WARN`` level. The ``ConsoleAppender`` is only provided as an example of +a non-Sentry appender that is set to a different logging threshold, like one you +may already have in your project. + +Example configuration using the ``logback.xml`` format: .. sourcecode:: xml - - ___DSN___?options - tag1:value1,tag2:value2 - - - - - - + + + + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + + + + + + + WARN + + + + + + + + -It's possible to add extra details to events captured by the logback -module thanks to the `marker system -`_ which will add a tag -logback-Marker. The `MDC system provided by logback -`_ allows to add extra information -to the event. +Next, **you'll need to configure your DSN** (client key) and optionally other values such as +``environment`` and ``release``. See below for the two ways you can do this. + +Configuration via Runtime Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the most flexible method for configuring the ``SentryAppender``, +because it can be easily changed based on the environment you run your +application in. + +The following can be set as System Environment variables: + +.. sourcecode:: shell + + SENTRY_EXAMPLE=xxx java -jar app.jar + +Or as Java System Properties: + +.. sourcecode:: shell + + java -Dsentry.example=xxx -jar app.jar + +Configuration parameters follow: + +======================= ======================= =============================== =========== +Environment variable Java System Property Example value Description +======================= ======================= =============================== =========== +``SENTRY_DSN`` ``sentry.dsn`` ``https://host:port/1?options`` Your Sentry DSN (client key), if left blank Raven will no-op +``SENTRY_RELEASE`` ``sentry.release`` ``1.0.0`` Optional, provide release version of your application +``SENTRY_ENVIRONMENT`` ``sentry.environment`` ``production`` Optional, provide environment your application is running in +``SENTRY_SERVERNAME`` ``sentry.servername`` ``server1`` Optional, override the server name (rather than looking it up dynamically) +``SENTRY_RAVENFACTORY`` ``sentry.ravenfactory`` ``com.foo.RavenFactory`` Optional, select the ravenFactory class +``SENTRY_TAGS`` ``sentry.tags`` ``tag1:value1,tag2:value2`` Optional, provide tags +``SENTRY_EXTRA_TAGS`` ``sentry.extratags`` ``foo,bar,baz`` Optional, provide tag names to be extracted from MDC +======================= ======================= =============================== =========== + +Configuration via Static File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also configure everything statically within the ``logback.xml`` +file itself. This is less flexible and not recommended because it's more difficult to change +the values when you run your application in different environments. + +Example configuration in the ``logback.xml`` file: + +.. sourcecode:: xml + + + + + + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + + + + + + + WARN + + + + https://host:port/1?options + + + 1.0.0 + + + production + + + server1 + + + com.foo.RavenFactory + + + tag1:value1,tag2:value2 + + + foo,bar,baz + + + + + + + + + +Additional Data +--------------- + +It's possible to add extra data to events thanks to `the MDC system provided by Logback +`_. Mapped Tags ------------ +~~~~~~~~~~~ -By default all MDC parameters are sent under the Additional Data Tab. By -specify the extraTags parameter in your configuration file. You can -specify MDC keys to send as tags instead of including them in Additional -Data. This allows them to be filtered within Sentry. +By default all MDC parameters are stored under the "Additional Data" tab in Sentry. By +specifying the ``extraTags`` parameter in your configuration file you can +choose which MDC keys to send as tags instead, which allows them to be used as +filters within the Sentry UI. .. sourcecode:: xml @@ -71,12 +188,12 @@ Data. This allows them to be filtered within Sentry. MDC.put("Environment", "Development"); MDC.put("OS", "Linux"); - // This adds a message with extras and MDC keys declared in extraTags as tags to Sentry - logger.info("This is a test"); + // This sends an event where the Environment and OS MDC values are set as tags + logger.error("This is a test"); } -Practical Example ------------------ +In Practice +----------- .. sourcecode:: java @@ -90,19 +207,19 @@ Practical Example private static final Marker MARKER = MarkerFactory.getMarker("myMarker"); void logSimpleMessage() { - // This adds a simple message to the logs - logger.info("This is a test"); + // This sends a simple event to Sentry + logger.error("This is a test"); } void logWithTag() { - // This adds a message with a tag to the logs named 'logback-Marker' + // This sends an event with a tag named 'logback-Marker' to Sentry logger.info(MARKER, "This is a test"); } void logWithExtras() { // MDC extras MDC.put("extra_key", "extra_value"); - // This adds a message with extras to the logs + // This sends an event with extra data to Sentry logger.info("This is a test"); } @@ -110,12 +227,12 @@ Practical Example try { unsafeMethod(); } catch (Exception e) { - // This adds an exception to the logs + // This sends an exception event to Sentry logger.error("Exception caught", e); } } void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); + throw new UnsupportedOperationException("You shouldn't call this!"); } } diff --git a/docs/modules/raven.rst b/docs/modules/raven.rst index 22ebc9ab83..71db9fd41f 100644 --- a/docs/modules/raven.rst +++ b/docs/modules/raven.rst @@ -1,18 +1,17 @@ -Raven -===== +java.util.logging +================= -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 +The ``raven`` library provides a `java.util.logging Handler `_ -for ``java.util.logging``. +that sends logged exceptions to Sentry. -The project can be found on github: `raven-java/raven -`_ +The source for ``raven-java`` can be found `on Github +`_. Installation ------------ -If you want to use Maven you can install Raven as dependency: +Using Maven: .. sourcecode:: xml @@ -22,29 +21,41 @@ If you want to use Maven you can install Raven as dependency: 7.8.2 -If you manually want to manage your dependencies: +Using Gradle: -- `jackson-core-2.5.0.jar `_ -- `slf4j-api-1.7.9.jar `_ -- `slf4j-jdk14-1.7.9.jar `_ - is recommended as the implementation of slf4j to capture the log events - generated by Raven (connection errors, ...) if `java.util.logging` is - used. +.. sourcecode:: groovy + + compile 'com.getsentry.raven:raven:7.8.2' + +Using SBT: + +.. sourcecode:: scala + + libraryDependencies += "com.getsentry.raven" % "raven" % "7.8.2" + +For other dependency managers see the `central Maven repository `_. Usage ----- -To use Raven you need to use it through ``java.util.logging``. The -following configuration (``logging.properties``) gets you started: +The following example configures a ``ConsoleHandler`` that logs to standard out +at the ``INFO`` level and a ``SentryHandler`` that logs to the Sentry server at +the ``WARN`` level. The ``ConsoleHandler`` is only provided as an example of +a non-Sentry appender that is set to a different logging threshold, like one you +may already have in your project. + +Example configuration using the ``logging.properties`` format: .. sourcecode:: ini - .level=WARNING - handlers=com.getsentry.raven.jul.SentryHandler - com.getsentry.raven.jul.SentryHandler.dsn=___DSN___ - com.getsentry.raven.jul.SentryHandler.tags=tag1:value1,tag2:value2 - # Optional, allows to select the ravenFactory - #com.getsentry.raven.jul.SentryHandler.ravenFactory=com.getsentry.raven.DefaultRavenFactory + # Enable the Console and Sentry handlers + handlers=java.util.logging.ConsoleHandler,com.getsentry.raven.jul.SentryHandler + + # Set the default log level to INFO + .level=INFO + + # Override the Sentry handler log level to WARNING + com.getsentry.raven.jul.SentryHandler.level=WARNING When starting your application, add the ``java.util.logging.config.file`` to the system properties, with the full path to the ``logging.properties`` as @@ -52,138 +63,109 @@ its value:: $ java -Djava.util.logging.config.file=/path/to/app.properties MyClass -Practical Example ------------------ +Next, **you'll need to configure your DSN** (client key) and optionally other values such as +``environment`` and ``release``. See below for the two ways you can do this. -.. sourcecode:: java +Configuration via Runtime Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - import java.util.logging.Level; - import java.util.logging.Logger; +This is the most flexible method for configuring the ``SentryHandler``, +because it can be easily changed based on the environment you run your +application in. - public class MyClass { - private static final Logger logger = Logger.getLogger(MyClass.class.getName()); +The following can be set as System Environment variables: - void logSimpleMessage() { - // This adds a simple message to the logs - logger.log(Level.INFO, "This is a test"); - } +.. sourcecode:: shell - void logException() { - try { - unsafeMethod(); - } catch (Exception e) { - // This adds an exception to the logs - logger.log(Level.SEVERE, "Exception caught", e); - } - } + SENTRY_EXAMPLE=xxx java -jar app.jar - void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); - } - } +Or as Java System Properties: -``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. +.. sourcecode:: shell -Manual Usage ------------- + java -Dsentry.example=xxx -jar app.jar -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: +Configuration parameters follow: -.. sourcecode:: java +======================= ======================= =============================== =========== +Environment variable Java System Property Example value Description +======================= ======================= =============================== =========== +``SENTRY_DSN`` ``sentry.dsn`` ``https://host:port/1?options`` Your Sentry DSN (client key), if left blank Raven will no-op +``SENTRY_RELEASE`` ``sentry.release`` ``1.0.0`` Optional, provide release version of your application +``SENTRY_ENVIRONMENT`` ``sentry.environment`` ``production`` Optional, provide environment your application is running in +``SENTRY_SERVERNAME`` ``sentry.servername`` ``server1`` Optional, override the server name (rather than looking it up dynamically) +``SENTRY_RAVENFACTORY`` ``sentry.ravenfactory`` ``com.foo.RavenFactory`` Optional, select the ravenFactory class +``SENTRY_TAGS`` ``sentry.tags`` ``tag1:value1,tag2:value2`` Optional, provide tags +``SENTRY_EXTRA_TAGS`` ``sentry.extratags`` ``foo,bar,baz`` Optional, provide tag names to be extracted from MDC +======================= ======================= =============================== =========== - import com.getsentry.raven.Raven; - import com.getsentry.raven.RavenFactory; +Configuration via Static File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - public class MyClass { - private static Raven raven; +You can also configure everything statically within the ``logging.properties`` +file itself. This is less flexible and not recommended because it's more difficult to change +the values when you run your application in different environments. - public static void main(String... args) { - // Creation of the client with a specific DSN - String dsn = args[0]; - raven = RavenFactory.ravenInstance(dsn); +Example configuration in the ``logging.properties`` file: - // It is also possible to use the DSN detection system like this - raven = RavenFactory.ravenInstance(); - } +.. sourcecode:: ini - void logSimpleMessage() { - // This adds a simple message to the logs - raven.sendMessage("This is a test"); - } + # Enable the Console and Sentry handlers + handlers=java.util.logging.ConsoleHandler, com.getsentry.raven.jul.SentryHandler - void logException() { - try { - unsafeMethod(); - } catch (Exception e) { - // This adds an exception to the logs - raven.sendException(e); - } - } + # Set the default log level to INFO + .level=INFO - void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); - } - } + # Override the Sentry handler log level to WARNING + com.getsentry.raven.jul.SentryHandler.level=WARNING -For more complex messages, it will be necessary to build an ``Event`` with the -``EventBuilder`` class: + # Set Sentry DSN + com.getsentry.raven.jul.SentryHandler.dsn=https://host:port/1?options -.. sourcecode:: java + # Optional, provide tags + com.getsentry.raven.jul.SentryHandler.tags=tag1:value1,tag2:value2 - 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; + # Optional, provide release version of your application + com.getsentry.raven.jul.SentryHandler.release=1.0.0 - public class MyClass { - private static Raven raven; + # Optional, provide environment your application is running in + com.getsentry.raven.jul.SentryHandler.environment=production - public static void main(String... args) { - // Creation of the client with a specific DSN - String dsn = args[0]; - raven = RavenFactory.ravenInstance(dsn); + # Optional, override the server name (rather than looking it up dynamically) + com.getsentry.raven.jul.SentryHandler.serverName=server1 - // It is also possible to use the DSN detection system like this - raven = RavenFactory.ravenInstance(); + # Optional, select the ravenFactory class + com.getsentry.raven.jul.SentryHandler.ravenFactory=com.foo.RavenFactory - // Advanced: To specify the ravenFactory used - raven = RavenFactory.ravenInstance(new Dsn(dsn), "com.getsentry.raven.DefaultRavenFactory"); - } + # Optional, provide tag names to be extracted from MDC + com.getsentry.raven.jul.SentryHandler.extraTags=foo,bar,baz + +In Practice +----------- + +.. sourcecode:: java + + 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 - 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()); + // This sends a simple event to Sentry + logger.error(Level.INFO, "This is a test"); } 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()); + // This sends an exception event to Sentry + logger.error(Level.SEVERE, "Exception caught", e); } } void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); + throw new UnsupportedOperationException("You shouldn't call this!"); } } diff --git a/docs/sentry-doc-config.json b/docs/sentry-doc-config.json index f34027f8ae..af1dd53d42 100644 --- a/docs/sentry-doc-config.json +++ b/docs/sentry-doc-config.json @@ -4,6 +4,15 @@ "java": { "name": "Java", "type": "language", + "doc_link": "", + "wizard": [ + "usage#installation", + "usage#capture-an-error" + ] + }, + "java.logging": { + "name": "java.util.logging", + "type": "framework", "doc_link": "modules/raven/", "wizard": [ "modules/raven#installation", @@ -11,7 +20,7 @@ ] }, "java.log4j": { - "name": "Log4j", + "name": "Log4j 1.x", "type": "framework", "doc_link": "modules/log4j/", "wizard": [ @@ -20,7 +29,7 @@ ] }, "java.log4j2": { - "name": "Log4j 2", + "name": "Log4j 2.x", "type": "framework", "doc_link": "modules/log4j2/", "wizard": [ @@ -38,13 +47,22 @@ ] }, "java.appengine": { - "name": "App Engine", + "name": "Google App Engine", "type": "framework", "doc_link": "modules/appengine/", "wizard": [ "modules/appengine#installation", "modules/appengine#usage" ] + }, + "java.android": { + "name": "Android", + "type": "framework", + "doc_link": "modules/android/", + "wizard": [ + "modules/android#installation", + "modules/android#usage" + ] } } } diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000000..f8a75125ea --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,177 @@ +Manual Usage +============ + +**Note:** The following page provides examples on how to configure and use +Raven directly. It is **highly recommended** that you use one of the provided +integrations instead if possible. + +Installation +------------ + +Using Maven: + +.. sourcecode:: xml + + + com.getsentry.raven + raven + 7.8.2 + + +Using Gradle: + +.. sourcecode:: groovy + + compile 'com.getsentry.raven:raven:7.8.2' + +Using SBT: + +.. sourcecode:: scala + + libraryDependencies += "com.getsentry.raven" % "raven" % "7.8.2" + +For other dependency managers see the `central Maven repository `_. + +Capture an Error +---------------- + +To report an event manually you need to construct a ``Raven`` instance and use one +of the send methods it provides. + +.. sourcecode:: java + + 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); + + // Or, if you don't provide a DSN, + raven = RavenFactory.ravenInstance(); + + // It is also possible to use the DSN detection system, which + // will check the environment variable "SENTRY_DSN" and the Java + // System Property "sentry.dsn". + raven = RavenFactory.ravenInstance(); + } + + void logSimpleMessage() { + // This sends a simple event to Sentry + raven.sendMessage("This is a test"); + } + + void logException() { + try { + unsafeMethod(); + } catch (Exception e) { + // This sends an exception event to Sentry + raven.sendException(e); + } + } + + void unsafeMethod() { + throw new UnsupportedOperationException("You shouldn't call this!"); + } + } + +Building More Complex Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For more complex messages, you'll need to build an ``Event`` with the +``EventBuilder`` class: + +.. sourcecode:: java + + 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, which + // will check the environment variable "SENTRY_DSN" and the Java + // System Property "sentry.dsn". + raven = RavenFactory.ravenInstance(); + + // Advanced: specify the ravenFactory used + raven = RavenFactory.ravenInstance(new Dsn(dsn), "com.getsentry.raven.DefaultRavenFactory"); + } + + void logSimpleMessage() { + // This sends an event to Sentry + EventBuilder eventBuilder = new EventBuilder() + .withMessage("This is a test") + .withLevel(Event.Level.INFO) + .withLogger(MyClass.class.getName()); + raven.sendEvent(eventBuilder); + } + + void logException() { + try { + unsafeMethod(); + } catch (Exception e) { + // This sends an exception event to Sentry + EventBuilder eventBuilder = new EventBuilder() + .withMessage("Exception caught") + .withLevel(Event.Level.ERROR) + .withLogger(MyClass.class.getName()) + .withSentryInterface(new ExceptionInterface(e)); + raven.sendEvent(eventBuilder); + } + } + + void unsafeMethod() { + throw new UnsupportedOperationException("You shouldn't call this!"); + } + } + +Static Access to Raven +---------------------- + +The most recently constructed ``Raven`` instance is stored statically so it may +be used easily from anywhere in your application. + +.. sourcecode:: java + + import com.getsentry.raven.Raven; + import com.getsentry.raven.RavenFactory; + + public class MyClass { + public static void main(String... args) { + // Create a Raven instance + RavenFactory.ravenInstance(); + } + + public somewhereElse() { + // Use the Raven instance statically. Note that we are + // using the Class (and a static method) here + Raven.capture("Error message"); + + // Or pass it a throwable + Raven.capture(new Exception("Error message")); + + // Or build an event yourself + EventBuilder eventBuilder = new EventBuilder() + .withMessage("Exception caught") + .withLevel(Event.Level.ERROR); + Raven.capture(eventBuilder.build()); + } + + } + +Note that a Raven instance *must* be created before you can use the ``Raven.capture`` +method, otherwise a ``NullPointerException`` (with an explanation) will be thrown. diff --git a/raven-android/README.md b/raven-android/README.md index 1397bf1b6c..a677e4fe59 100644 --- a/raven-android/README.md +++ b/raven-android/README.md @@ -1,61 +1,3 @@ -# Raven-Android +# raven-android -## Installation - -### Gradle (Android Studio) - -In your `app/build.gradle` add: `compile 'com.getsentry.raven:raven-android:7.8.2'` - -### Other dependency managers -Details in the [central Maven repository](https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven-android%7C7.8.2%7Cjar). - -## Usage - -### Configuration - -Configure your Sentry DSN (client key) in `AndroidManifest.xml`: - -```xml - - - -``` - -Your application must also have permission to access the internet in order to send -event to the Sentry server. In `AndroidManifest.xml`: - -```xml - - -``` - -Then, in your application's `onCreate`, initialize the Raven client: - -```java -import com.getsentry.raven.android.Raven; - -// `this` is your main Activity -Raven.init(this.getApplicationContext()); -``` - -Now you can use `Raven` to capture events in your application: - -```java -// Pass a String event -Raven.capture("Error message"); - -// Or pass it a throwable -try { - something() -} catch (Exception e) { - Raven.capture(e); -} - -// Or build an event yourself -EventBuilder eventBuilder = new EventBuilder() - .withMessage("Exception caught") - .withLevel(Event.Level.ERROR); -Raven.capture(eventBuilder.build()); -``` +See the [Sentry documentation](https://docs.sentry.io/clients/java/modules/android/) for more information. diff --git a/raven-appengine/README.md b/raven-appengine/README.md index 40be559f24..1be84b4b93 100644 --- a/raven-appengine/README.md +++ b/raven-appengine/README.md @@ -1,52 +1,3 @@ -# AppEngine (module) -Module enabling the support of the async connections in Google App Engine. +# raven-appengine -Google App Engine doesn't support threads but provides instead a TaskQueueing system allowing tasks to be run in the -background. - -This module replaces the async system provided by default with one relying on the tasks. - -__This module is not useful outside of Google App Engine.__ - -## Installation - -### Maven -```xml - - com.getsentry.raven - raven-appengine - 7.8.2 - -``` - -### Gradle -``` -compile 'com.getsentry.raven:raven-appengine:7.8.2' -``` - -### Other dependency managers -Details in the [central Maven repository](https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven-appengine%7C7.8.2%7Cjar). - -## Usage - -This module provides a new `RavenFactory` which replaces the default async system with a GAE compatible one. - -The queue size and thread options will not be used as they are specific to the default multithreaded system. - -It is necessary to force the raven factory name to `com.getsentry.raven.appengine.AppEngineRavenFactory`. - -### Queue name - -By default, the default task queue will be used, but it's possible to specify which one will be used with the -`raven.async.gae.queuename` option: - - http://public:private@getsentry.com/1?raven.async.gae.queuename=MyQueueName - -### Connection name - -As the queued tasks are sent across different instances of the application, it's important to be able to identify which -connection should be used when processing the event. -To do so, the GAE module will identify each connection based on an identifier either automatically generated or user defined. -TO manually set the connection identifier (only used internally) use the option `raven.async.connectionid`: - - http://public:private@getsentry.com/1?raven.async.gae.connectionid=MyConnection +See the [Sentry documentation](https://docs.sentry.io/clients/java/modules/appengine/) for more information. diff --git a/raven-appengine/src/main/java/com/getsentry/raven/appengine/connection/AppEngineAsyncConnection.java b/raven-appengine/src/main/java/com/getsentry/raven/appengine/connection/AppEngineAsyncConnection.java index bd29e133d3..f5a6205d8b 100644 --- a/raven-appengine/src/main/java/com/getsentry/raven/appengine/connection/AppEngineAsyncConnection.java +++ b/raven-appengine/src/main/java/com/getsentry/raven/appengine/connection/AppEngineAsyncConnection.java @@ -18,10 +18,10 @@ import static com.google.appengine.api.taskqueue.TaskOptions.Builder.withPayload; /** - * Asynchronous usage of a connection withing Google App Engine. + * Asynchronous connections that can be used within Google App Engine. *

- * Instead of synchronously sending each event to a connection, use a the task queue system to establish the connection - * and submit the event. + * Instead of synchronously sending each event, use a the App Engine queue system to establish the connection + * and send the event. *

* Google App Engine serialises the tasks before queuing them, to keep a link between the task and the * {@link AppEngineAsyncConnection} associated, a register of the instances of {@code AppEngineAsyncConnection} is diff --git a/raven-log4j/README.md b/raven-log4j/README.md index 47655083cf..498cff6884 100644 --- a/raven-log4j/README.md +++ b/raven-log4j/README.md @@ -1,197 +1,3 @@ -# Raven-log4j -[log4j](https://logging.apache.org/log4j/1.2/) support for Raven. -It provides an [`Appender`](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Appender.html) -for log4j to send the logged events to Sentry. +# raven-log4j -## Installation - -### Maven -```xml - - com.getsentry.raven - raven-log4j - 7.8.2 - -``` - -### Gradle -``` -compile 'com.getsentry.raven:raven-log4j:7.8.2' -``` - -### Other dependency managers -Details in the [central Maven repository](https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven-log4j%7C7.8.2%7Cjar). - -## Usage -### Configuration -Add the `SentryAppender` to the `log4j.properties` file: - -```properties -# Enable the Console and Sentry appenders -log4j.rootLogger=INFO, Console, Sentry - -# Configure the Console appender -log4j.appender.Console=org.apache.log4j.ConsoleAppender -log4j.appender.Console.layout=org.apache.log4j.PatternLayout -log4j.appender.Console.layout.ConversionPattern=%d{HH:mm:ss.SSS} [%t] %-5p: %m%n - -# Configure the Sentry appender, overriding the logging threshold to the WARN level -log4j.appender.Sentry=com.getsentry.raven.log4j.SentryAppender -log4j.appender.Sentry.threshold=WARN -``` - -Alternatively in the `log4j.xml` file add: - -``` - - - - - - -``` - -You'll also need to associate the `Sentry` appender with your root logger, like so: - -``` - --> - - -``` - -Next, you'll need to configure your DSN (client key) and optionally other -values such as `environment` and `release`. See below for the two -ways you can do this. - -#### Configuration via runtime environment - -This is the most flexible method to configure the `SentryAppender`, -because it can be easily changed based on the environment you run your -application in. - -The following can be set as System Environment variables: - -```bash -SENTRY_EXAMPLE=xxx java -jar app.jar -``` - -or as Java System Properties: - -```bash -java -Dsentry.example=xxx -jar app.jar -``` - -Configuration parameters follow: - -| Environment variable | Java System Property | Example value | Description | -|---|---|---|---| -| `SENTRY_DSN` | `sentry.dsn` | `https://host:port/1?options` | Your Sentry DSN (client key), if left blank Raven will no-op | -| `SENTRY_RELEASE` | `sentry.release` | `1.0.0` | Optional, provide release version of your application | -| `SENTRY_ENVIRONMENT` | `sentry.environment` | `production` | Optional, provide environment your application is running in | -| `SENTRY_SERVERNAME` | `sentry.servername` | `server1` | Optional, override the server name (rather than looking it up dynamically) | -| `SENTRY_RAVENFACTORY` | `sentry.ravenfactory` | `com.foo.RavenFactory` | Optional, select the ravenFactory class | -| `SENTRY_TAGS` | `sentry.tags` | `tag1:value1,tag2:value2` | Optional, provide tags | -| `SENTRY_EXTRA_TAGS` | `sentry.extratags` | `foo,bar,baz` | Optional, provide tag names to be extracted from MDC when using SLF4J | - -#### Configuration via `log4j.properties` (or `log4j.xml`) - -You can also configure everything statically within the `log4j.properties` (or `log4j.xml`) -file itself. This is less flexible because it's harder to change when you run -your application in different environments. - -```properties -# Enable the Console and Sentry appenders -log4j.rootLogger=INFO, Console, Sentry - -# Configure the Console appender -log4j.appender.Console=org.apache.log4j.ConsoleAppender - -# Configure the Sentry appender, overriding the logging threshold to the WARN level -log4j.appender.Sentry=com.getsentry.raven.log4j.SentryAppender -log4j.appender.Sentry.threshold=WARN - -# Set Sentry DSN -log4j.appender.SentryAppender.dsn=https://host:port/1?options -# Optional, provide release version of your application -log4j.appender.SentryAppender.release=1.0.0 -# Optional, provide environment your application is running in -log4j.appender.SentryAppender.environment=production -# Optional, override the server name (rather than looking it up dynamically) -log4j.appender.SentryAppender.serverName=server1 -# Optional, select the ravenFactory class -log4j.appender.SentryAppender.ravenFactory=com.foo.RavenFactory -# Optional, provide tags -log4j.appender.SentryAppender.tags=tag1:value1,tag2:value2 -# Optional, provide tag names to be extracted from MDC when using SLF4J -log4j.appender.SentryAppender.extraTags=foo,bar,baz -``` - -### Additional data and information -It's possible to add extra data to events, -thanks to both [the MDC](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html) -and [the NDC](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/NDC.html) systems provided by Log4j. - -### In practice -```java -import org.apache.log4j.Logger; -import org.apache.log4j.MDC; -import org.apache.log4j.NDC; - -public class MyClass { - private static final Logger logger = Logger.getLogger(MyClass.class); - - void logSimpleMessage() { - // This adds a simple message to the logs - logger.info("This is a test"); - } - - void logWithExtras() { - // MDC extras - MDC.put("extra_key", "extra_value"); - // NDC extras are sent under 'log4J-NDC' - NDC.push("Extra_details"); - // This adds a message with extras to the logs - logger.info("This is a test"); - } - - void logException() { - try { - unsafeMethod(); - } catch (Exception e) { - // This adds an exception to the logs - logger.error("Exception caught", e); - } - } - - void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); - } -} -``` - -### Mapped Tags -By default all MDC parameters are sent under the Additional Data Tab. By specify the extraTags parameter in your -configuration file. You can specify MDC keys to send as tags instead of including them in Additional Data. -This allows them to be filtered within Sentry. - -```properties -log4j.appender.SentryAppender.extraTags=User,OS -``` -```java - void logWithExtras() { - // MDC extras - MDC.put("User", "test user"); - MDC.put("OS", "Linux"); - - // This adds a message with extras and MDC keys declared in extraTags as tags to Sentry - logger.info("This is a test"); - } -``` - -## Asynchronous logging -It is not recommended to attempt to set up `SentryAppender` within an -[AsyncAppender](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/AsyncAppender.html). -While this is a common solution to avoid blocking the current thread until the -event is sent to Sentry, it is recommended to rely instead on the asynchronous -connection provided by Raven. +See the [Sentry documentation](https://docs.sentry.io/clients/java/modules/log4j/) for more information. diff --git a/raven-log4j2/README.md b/raven-log4j2/README.md index 54445bc1a2..879e7e67a1 100644 --- a/raven-log4j2/README.md +++ b/raven-log4j2/README.md @@ -1,194 +1,3 @@ -# Raven-Log4j 2 -[Log4j 2](https://logging.apache.org/log4j/2.x/) support for Raven. -It provides an [`Appender`](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html) -for Log4j 2 to send the logged events to Sentry. +# raven-log4j 2.x -## Installation - -### Maven -```xml - - com.getsentry.raven - raven-log4j2 - 7.8.2 - -``` - -### Gradle -``` -compile 'com.getsentry.raven:raven-log4j2:7.8.2' -``` - -### Other dependency managers -Details in the [central Maven repository](https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven-log4j2%7C7.8.2%7Cjar). - -## Usage -### Configuration -Add the `SentryAppender` to your `log4j2.xml` file: - -```xml - - - - - - - - - - - - - - - - - -``` - -Next, you'll need to configure your DSN (client key) and optionally other -values such as `environment` and `release`. See below for the two -ways you can do this. - -#### Configuration via runtime environment - -This is the most flexible method to configure the `SentryAppender`, -because it can be easily changed based on the environment you run your -application in. - -The following can be set as System Environment variables: - -```bash -SENTRY_EXAMPLE=xxx java -jar app.jar -``` - -or as Java System Properties: - -```bash -java -Dsentry.example=xxx -jar app.jar -``` - -Configuration parameters follow: - -| Environment variable | Java System Property | Example value | Description | -|---|---|---|---| -| `SENTRY_DSN` | `sentry.dsn` | `https://host:port/1?options` | Your Sentry DSN (client key), if left blank Raven will no-op | -| `SENTRY_RELEASE` | `sentry.release` | `1.0.0` | Optional, provide release version of your application | -| `SENTRY_ENVIRONMENT` | `sentry.environment` | `production` | Optional, provide environment your application is running in | -| `SENTRY_SERVERNAME` | `sentry.servername` | `server1` | Optional, override the server name (rather than looking it up dynamically) | -| `SENTRY_RAVENFACTORY` | `sentry.ravenfactory` | `com.foo.RavenFactory` | Optional, select the ravenFactory class | -| `SENTRY_TAGS` | `sentry.tags` | `tag1:value1,tag2:value2` | Optional, provide tags | -| `SENTRY_EXTRA_TAGS` | `sentry.extratags` | `foo,bar,baz` | Optional, provide tag names to be extracted from MDC when using SLF4J | - -#### Configuration via `log4j2.xml` - -You can also configure everything statically within the `log4j2.xml` file -itself. This is less flexible because it's harder to change when you run -your application in different environments. - -```xml - - - - - - - - - https://host:port/1?options - - 1.0.0 - - production - - server1 - - com.foo.RavenFactory - - tag1:value1,tag2:value2 - - foo,bar,baz - - - - - - - - - - -``` - -### Additional data and information -It's possible to add extra details to events captured by the Log4j 2 module -thanks to the [marker system](https://logging.apache.org/log4j/2.x/manual/markers.html) -which will add a tag `log4j2-Marker`. -Both [the MDC and the NDC systems provided by Log4j 2](https://logging.apache.org/log4j/2.x/manual/thread-context.html) -are usable, allowing to attach extras information to the event. - -### Mapped Tags -By default all Thread Context parameters are sent under the Additional Data Tab. By specifying the extraTags parameter in your -configuration file. You can specify Thread Context keys to send as tags instead of including them in Additional Data. -This allows them to be filtered within Sentry. In older Log4j versions, the Thread Context Map was known as the MDC. - -```xml - - User,OS - -``` -```java - void logWithExtras() { - // ThreadContext extras - ThreadContext.put("User", "test user"); - ThreadContext.put("OS", "Linux"); - - // This adds a message with extras and ThreadContext keys declared in extraTags as tags to Sentry - logger.info("This is a test"); - } -``` - -### In practice -```java -import org.apache.logging.log4j.LogManager; -import org.apache.logging.log4j.Logger; -import org.apache.logging.log4j.Marker; -import org.apache.logging.log4j.MarkerManager; - -public class MyClass { - private static final Logger logger = LogManager.getLogger(MyClass.class); - private static final Marker MARKER = MarkerManager.getMarker("myMarker"); - - void logSimpleMessage() { - // This adds a simple message to the logs - logger.info("This is a test"); - } - - void logWithTag() { - // This adds a message with a tag to the logs named 'log4j2-Marker' - logger.info(MARKER, "This is a test"); - } - - void logWithExtras() { - // MDC extras - ThreadContext.put("extra_key", "extra_value"); - // NDC extras are sent under 'log4j2-NDC' - ThreadContext.push("Extra_details"); - // This adds a message with extras to the logs - logger.info("This is a test"); - } - - void logException() { - try { - unsafeMethod(); - } catch (Exception e) { - // This adds an exception to the logs - logger.error("Exception caught", e); - } - } - - void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); - } -} -``` +See the [Sentry documentation](https://docs.sentry.io/clients/java/modules/log4j2/) for more information. diff --git a/raven-logback/README.md b/raven-logback/README.md index 035e3c579c..9a203a9d6e 100644 --- a/raven-logback/README.md +++ b/raven-logback/README.md @@ -1,193 +1,3 @@ -# Raven-logback -[logback](http://logback.qos.ch/) support for Raven. -It provides an [`Appender`](http://logback.qos.ch/apidocs/ch/qos/logback/core/Appender.html) -for logback to send the logged events to Sentry. +# raven-logback -## Installation - -### Maven -```xml - - com.getsentry.raven - raven-logback - 7.8.2 - -``` - -### Gradle -``` -compile 'com.getsentry.raven:raven-logback:7.8.2' -``` - -### Other dependency managers -Details in the [central Maven repository](https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven-logback%7C7.8.2%7Cjar). - -## Usage -### Configuration -Add the `SentryAppender` to your `logback.xml` file: - -```xml - - - - %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n - - - - - - WARN - - - - - - - - -``` - -Next, you'll need to configure your DSN (client key) and optionally other -values such as `environment` and `release`. See below for the two -ways you can do this. - -#### Configuration via runtime environment - -This is the most flexible method to configure the `SentryAppender`, -because it can be easily changed based on the environment you run your -application in. - -The following can be set as System Environment variables: - -```bash -SENTRY_EXAMPLE=xxx java -jar app.jar -``` - -or as Java System Properties: - -```bash -java -Dsentry.example=xxx -jar app.jar -``` - -Configuration parameters follow: - -| Environment variable | Java System Property | Example value | Description | -|---|---|---|---| -| `SENTRY_DSN` | `sentry.dsn` | `https://host:port/1?options` | Your Sentry DSN (client key), if left blank Raven will no-op | -| `SENTRY_RELEASE` | `sentry.release` | `1.0.0` | Optional, provide release version of your application | -| `SENTRY_ENVIRONMENT` | `sentry.environment` | `production` | Optional, provide environment your application is running in | -| `SENTRY_SERVERNAME` | `sentry.servername` | `server1` | Optional, override the server name (rather than looking it up dynamically) | -| `SENTRY_RAVENFACTORY` | `sentry.ravenfactory` | `com.foo.RavenFactory` | Optional, select the ravenFactory class | -| `SENTRY_TAGS` | `sentry.tags` | `tag1:value1,tag2:value2` | Optional, provide tags | -| `SENTRY_EXTRA_TAGS` | `sentry.extratags` | `foo,bar,baz` | Optional, provide tag names to be extracted from MDC when using SLF4J | - -#### Configuration via `logback.xml` - -You can also configure everything statically within the `logback.xml` file -itself. This is less flexible because it's harder to change when you run -your application in different environments. - -```xml - - - - %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n - - - - - - WARN - - - - https://host:port/1?options - - 1.0.0 - - production - - server1 - - com.foo.RavenFactory - - tag1:value1,tag2:value2 - - foo,bar,baz - - - - - - - -``` - -### Additional data and information -It's possible to add extra details to events captured by the logback module -thanks to the [marker system](http://www.slf4j.org/faq.html#fatal) which will -add a tag `logback-Marker`. -[The MDC system provided by logback](http://logback.qos.ch/manual/mdc.html) -allows to add extra information to the event. - -### Mapped Tags -By default all MDC parameters are sent under the Additional Data Tab. By specifying the extraTags parameter in your -configuration file. You can specify MDC keys to send as tags instead of including them in Additional Data. -This allows them to be filtered within Sentry. - -```xml -User,OS -``` -```java - void logWithExtras() { - // MDC extras - MDC.put("User", "test user"); - MDC.put("OS", "Linux"); - - // This adds a message with extras and MDC keys declared in extraTags as tags to Sentry - logger.info("This is a test"); - } -``` - -### In practice -```java -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; -import org.slf4j.MDC; -import org.slf4j.MarkerFactory; - -public class MyClass { - private static final Logger logger = LoggerFactory.getLogger(MyClass.class); - private static final Marker MARKER = MarkerFactory.getMarker("myMarker"); - - void logSimpleMessage() { - // This adds a simple message to the logs - logger.info("This is a test"); - } - - void logWithTag() { - // This adds a message with a tag to the logs named 'logback-Marker' - logger.info(MARKER, "This is a test"); - } - - void logWithExtras() { - // MDC extras - MDC.put("extra_key", "extra_value"); - // This adds a message with extras to the logs - logger.info("This is a test"); - } - - void logException() { - try { - unsafeMethod(); - } catch (Exception e) { - // This adds an exception to the logs - logger.error("Exception caught", e); - } - } - - void unsafeMethod() { - throw new UnsupportedOperationException("You shouldn't call that"); - } -} -``` +See the [Sentry documentation](https://docs.sentry.io/clients/java/modules/logback/) for more information. diff --git a/raven/README.md b/raven/README.md index 838ee94ad6..7b34e2f3f2 100644 --- a/raven/README.md +++ b/raven/README.md @@ -1,284 +1,3 @@ -# 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`](http://docs.oracle.com/javase/7/docs/api/java/util/logging/Handler.html) -for `java.util.logging`. +# raven -## Installation - -### Maven -```xml - - com.getsentry.raven - raven - 7.8.2 - -``` - -### Gradle -``` -compile 'com.getsentry.raven:raven:7.8.2' -``` - -### Other dependency managers -Details in the [central Maven repository](https://search.maven.org/#artifactdetails%7Ccom.getsentry.raven%7Craven%7C7.8.2%7Cjar). - -## Usage (`java.util.logging`) -### Configuration -Add the `SentryHandler` to the `logging.properties` file: - -```properties -# Enable the Console and Sentry handlers -handlers=java.util.logging.ConsoleHandler,com.getsentry.raven.jul.SentryHandler - -# Set the default log level to INFO -.level=INFO - -# Override the Sentry handler log level to WARNING -com.getsentry.raven.jul.SentryHandler.level=WARNING -``` - -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 - -Next, you'll need to configure your DSN (client key) and optionally other -values such as `environment` and `release`. See below for the two -ways you can do this. - -#### Configuration via runtime environment - -This is the most flexible method to configure the `SentryAppender`, -because it can be easily changed based on the environment you run your -application in. - -The following can be set as System Environment variables: - -```bash -SENTRY_EXAMPLE=xxx java -jar app.jar -``` - -or as Java System Properties: - -```bash -java -Dsentry.example=xxx -jar app.jar -``` - -Configuration parameters follow: - -| Environment variable | Java System Property | Example value | Description | -|---|---|---|---| -| `SENTRY_DSN` | `sentry.dsn` | `https://host:port/1?options` | Your Sentry DSN (client key), if left blank Raven will no-op | -| `SENTRY_RELEASE` | `sentry.release` | `1.0.0` | Optional, provide release version of your application | -| `SENTRY_ENVIRONMENT` | `sentry.environment` | `production` | Optional, provide environment your application is running in | -| `SENTRY_SERVERNAME` | `sentry.servername` | `server1` | Optional, override the server name (rather than looking it up dynamically) | -| `SENTRY_RAVENFACTORY` | `sentry.ravenfactory` | `com.foo.RavenFactory` | Optional, select the ravenFactory class | -| `SENTRY_TAGS` | `sentry.tags` | `tag1:value1,tag2:value2` | Optional, provide tags | -| `SENTRY_EXTRA_TAGS` | `sentry.extratags` | `foo,bar,baz` | Optional, provide tag names to be extracted from MDC when using SLF4J | - -#### Configuration via `logging.properties` - -You can also configure everything statically within the `logging.properties` file -itself. This is less flexible because it's harder to change when you run -your application in different environments. - -```properties -# Enable the Console and Sentry handlers -handlers=java.util.logging.ConsoleHandler,com.getsentry.raven.jul.SentryHandler - -# Set the default log level to INFO -.level=INFO - -# Override the Sentry handler log level to WARNING -com.getsentry.raven.jul.SentryHandler.level=WARNING - -# Set Sentry DSN -com.getsentry.raven.jul.SentryHandler.dsn=https://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, provide environment your application is running in -com.getsentry.raven.jul.SentryHandler.environment=production -# 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.foo.RavenFactory -# Optional, provide tag names to be extracted from MDC when using SLF4J -com.getsentry.raven.jul.SentryHandler.extraTags=foo,bar,baz -``` - -### In practice -```java -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 - -As `java.util.logging` has no notion of MDC, the `extraTags` parameter is only -available when logging via SLF4J. - -## 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 -```java -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. - -```java -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. - -### Static access - -The most recently constructed `Raven` instance is stored statically so it may -be used easily from anywhere in your application. - -```java -import com.getsentry.raven.Raven; -import com.getsentry.raven.RavenFactory; - -public class MyClass { - public static void main(String... args) { - // Create a Raven instance - RavenFactory.ravenInstance(); - } - - public somewhereElse() { - // Use the Raven instance statically. Note that we are - // using the Class (and a static method) here - Raven.capture("Error message"); - - // Or pass it a throwable - Raven.capture(new Exception("Error message")); - - // Or build an event yourself - EventBuilder eventBuilder = new EventBuilder() - .withMessage("Exception caught") - .withLevel(Event.Level.ERROR); - Raven.capture(eventBuilder.build()); - } - -} -``` - -Note that a Raven instance *must* be created before you can use the `Raven.capture` -method, otherwise a `NullPointerException` (with an explaination) will be thrown. +See the [Sentry documentation](https://docs.sentry.io/clients/java/modules/raven/) for more information.