`_.
+
+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.