bumped version to 0.4 and did a little cleanup and added more documen…

…tation

README.rst

@@ -6,6 +6,15 @@ This is a very raw project at the moment it still needs some more TLC and testin
 
 Installation
 ------------
+
+Download Jars
+~~~~~~~~~~~~~
+Precompiled jars are available for download directly from github.
+
+    https://github.com/kencochrane/raven-java/downloads
+
+Build Jars yourself
+~~~~~~~~~~~~~~~~~~~
 You'll need Maven 2 to build the project::
 
     $ cd raven-java
@@ -19,15 +28,18 @@ you'll find in the target directory of the project.
     <dependency>
         <groupId>net.kencochrane</groupId>
         <artifactId>raven-java</artifactId>
-        <version>0.3-SNAPSHOT</version>
+        <version>0.4-SNAPSHOT</version>
     </dependency>
 
 **Option 2**: add the plain jar and the jar files of all dependencies to your classpath
 
 **Option 3**: add the self contained jar file to your classpath
 
+Configuration
+-------------
+
 Log4J configuration
--------------------
+*******************
 Check out src/test/java/resources/log4j_configuration.txt where you can see an example log4j config file.
 
 You will need to add the SentryAppender and the sentry_dsn properties.
@@ -48,6 +60,63 @@ If you need to use a proxy for HTTP transport, you can configure it as well::
 
     log4j.appender.sentry.proxy=HTTP:proxyhost:proxyport
 
+SENTRY_DSN Environment Variable
+*******************************
+Raven-Java will first look to see if there is an environment variable called ``SENTRY_DSN`` set before it looks at the log4j config. If the environment variable is set, it will use that value instead of the one set in ``log4j.appender.sentry.sentry_dsn``. This is for a few reasons.
+
+1. Some hosting providers (Heroku, etc) have http://GetSentry.com plugins and they expose your Sentry settings via an environment variable. 
+2. This allows you to specify your Sentry config by server. You could put a development Sentry server in your log4j properties file and then on each server override those values to point to different sentry servers if you need to.
+3. It allows you to use the RavenClient directly outside of log4J, without having to hard code the Sentry DSN in your source code.
+
+Linux example::
+    # put this in your profile, or add it to a shell script that calls your java program.
+    export SENTRY_DSN=http://b4935bdd78624092ac2bc70fdcdb6f5a:7a37d9ad4765428180316bfec91a27ef@localhost:8000/1
+
+Usage
+-----
+
+Log4J
+~~~~~
+
+If you configure log4j to only error messages to Sentry, it will ignore all other message levels and only send the logger.error() messages
+
+Example::
+
+    // configure log4j the normal way, and then just use it like you normally would.
+    
+    logger.debug("Debug example"); // ignored
+    logger.error("Error example"); // sent to sentry
+    logger.info("info Example"); // ignored
+    
+    try {
+        throw new RuntimeException("Uh oh!");
+    } catch (RuntimeException e) {
+        logger.error("Error example with stacktrace", e); //sent to sentry
+    }
+
+
+RavenClient
+~~~~~~~~~~~
+Set the SENTRY_DSN Environment Variable with your sentry DSN.
+
+Create an instance of the client:
+
+    RavenClient client = new RavenClient();
+
+Now call out to the raven client to capture events::
+
+    // record a simple message
+    client.captureMessage('hello world!')
+
+    // capture an exception
+    try {
+        throw new RuntimeException("Uh oh!");
+    }
+    catch (Throwable e) {
+        client.captureException(e);
+    }
+
+
 Sentry Versions Supported
 -------------------------
 This client supports Sentry protocol version 2.0 (which is Sentry >= 2.0)
@@ -57,6 +126,10 @@ Other
 If you want to generate the javadocs for this project, simply run ``mvn javadoc:javadoc`` and you'll be able to browse the
 docs from the target directory of the project.
 
+Running Tests
+-------------
+We are using maven, so all that you need to do in order to run the test is run ``mvn test``.
+
 TODO
 ----
 - Create better documentation
@@ -67,6 +140,10 @@ TODO
 
 History
 -------
+- 0.4
+    - Added the ability to get the SENTRY_DSN from the ENV
+    - Added RavenClient.captureMessage
+    - Added RavenClient.captureException
 - 0.3
     - Added Maven support
     - Merged with log4sentry project by Kevin Wetzels
@@ -82,4 +159,5 @@ History
 Contributors
 ------------
 - Ken Cochrane (@KenCochrane)
-- Kevin Wetzels (@roambe)
+- Kevin Wetzels (@roambe)
+- David Cramer (@zeeg)

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>net.kencochrane</groupId>
     <artifactId>raven-java</artifactId>
-    <version>0.3-SNAPSHOT</version>
+    <version>0.4-SNAPSHOT</version>
     <packaging>jar</packaging>
     <name>raven-java</name>
     <description>Java Raven client and log4j appender.</description>
@@ -51,6 +51,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
+                <version>2.3.2</version>
                 <configuration>
                     <source>1.6</source>
                     <target>1.6</target>
@@ -60,6 +61,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-resources-plugin</artifactId>
+                <version>2.5</version>
                 <configuration>
                     <encoding>UTF-8</encoding>
                     <outputDirectory/>

src/main/java/net/kencochrane/sentry/RavenClient.java

@@ -19,7 +19,7 @@
 
 class RavenClient {
 
-    private static final String RAVEN_JAVA_VERSION = "Raven-Java 0.2";
+    private static final String RAVEN_JAVA_VERSION = "Raven-Java 0.4";
     private RavenConfig config;
     private String sentryDSN;
     private String lastID;
@@ -262,7 +262,7 @@ private void sendMessage(String messageBody, long timestamp) {
     /**
      * Send the log message to the sentry server.
      *
-     * This method is deprecated. You should use captureMessage instead.
+     * This method is deprecated. You should use captureMessage or captureException instead.
      *
      * @deprecated
      * @param theLogMessage The log message
@@ -273,9 +273,7 @@ private void sendMessage(String messageBody, long timestamp) {
      * @param exception     exception that occurred
      */
     public void logMessage(String theLogMessage, long timestamp, String loggerClass, int logLevel, String culprit, Throwable exception) {
-        String timestampDate = RavenUtils.getTimestampString(timestamp);
-
-        String message = buildMessage(theLogMessage, timestampDate, loggerClass, logLevel, culprit, exception);
+        String message = buildMessage(theLogMessage, RavenUtils.getTimestampString(timestamp), loggerClass, logLevel, culprit, exception);
         sendMessage(message, timestamp);
     }
 
@@ -288,39 +286,48 @@ public void logMessage(String theLogMessage, long timestamp, String loggerClass,
      * @param loggerClass   The class associated with the log message
      * @param logLevel      int value for Log level for message (DEBUG, ERROR, INFO, etc.)
      * @param culprit       Who we think caused the problem.
+     * @return lastID       The ID for the last message.
      */
     public String captureMessage(String message, long timestamp, String loggerClass, int logLevel, String culprit) {
-        String timestampDate = RavenUtils.getTimestampString(timestamp);
-
-        String body = buildMessage(message, timestampDate, loggerClass, logLevel, culprit, null);
+        String body = buildMessage(message, RavenUtils.getTimestampString(timestamp), loggerClass, logLevel, culprit, null);
         sendMessage(body, timestamp);
         return getLastID();
     }
 
+    /**
+     * Send the log message to the sentry server.
+     *
+     * @param message       The log message
+     * @return lastID       The ID for the last message.
+     */
     public String captureMessage(String message) {
-        long timestamp = System.currentTimeMillis() / 1000L;
-        return captureMessage(message, timestamp, "root", 50, null);
+        return captureMessage(message, RavenUtils.getTimestampLong(), "root", 50, null);
     }
 
     /**
-     * Send the log message to the sentry server.
+     * Send the exception to the sentry server.
      *
-     * @param exception     exception that occurred
+     * @param message       The log message
      * @param timestamp     unix timestamp
      * @param loggerClass   The class associated with the log message
      * @param logLevel      int value for Log level for message (DEBUG, ERROR, INFO, etc.)
      * @param culprit       Who we think caused the problem.
+     * @param exception     exception that occurred
+     * @return lastID       The ID for the last message.
      */
-    public String captureException(Throwable exception, long timestamp, String loggerClass, int logLevel, String culprit) {
-        String timestampDate = RavenUtils.getTimestampString(timestamp);
-
-        String body = buildMessage(exception.getMessage(), timestampDate, loggerClass, logLevel, culprit, exception);
+    public String captureException(String message, long timestamp, String loggerClass, int logLevel, String culprit, Throwable exception) {
+        String body = buildMessage(message, RavenUtils.getTimestampString(timestamp), loggerClass, logLevel, culprit, exception);
         sendMessage(body, timestamp);
         return getLastID();
     }
 
+    /**
+     * Send an exception to the sentry server.
+     *
+     * @param exception     exception that occurred
+     * @return lastID       The ID for the last message. 
+     */
     public String captureException(Throwable exception) {
-        long timestamp = System.currentTimeMillis() / 1000L;
-        return captureException(exception, timestamp, "root", 50, null);
+        return captureException(exception.getMessage(), RavenUtils.getTimestampLong(), "root", 50, null, exception);
     }
 }

src/main/java/net/kencochrane/sentry/SentryAppender.java

@@ -30,13 +30,26 @@ public void setProxy(String proxy) {
         this.proxy = proxy;
     }
 
+    /**
+    * Look for the ENV variable first, and if it isn't there, then look in the log4j properties
+    *
+    */
+    private String findSentryDSN(){
+        String sentryDSN = System.getenv("SENTRY_DSN");
+        if (sentryDSN == null || sentryDSN.length() == 0) {
+            sentryDSN = getSentry_dsn();
+            if (sentryDSN == null) {
+                throw new RuntimeException("ERROR: You do not have a Sentry DSN configured! make sure you add sentry_dsn to your log4j properties, or have set SENTRY_DSN as an envirornment variable.");
+            }
+        }
+        return sentryDSN;
+    }
+
     @Override
     protected void append(LoggingEvent loggingEvent) {
 
-        if (getSentry_dsn() == null) {
-            System.err.println("ERROR: You do not have a Sentry DSN configured! make sure you add sentry_dsn to your log4j properties ");
-            return;
-        }
+        //find the sentry DSN.
+        String sentryDSN = findSentryDSN();
 
         synchronized (this) {
             try {
@@ -50,12 +63,17 @@ protected void append(LoggingEvent loggingEvent) {
                 String culprit = loggingEvent.getLoggerName();
 
                 // create the client passing in the sentry DSN from the log4j properties file.
-                RavenClient client = new RavenClient(getSentry_dsn(), getProxy());
+                RavenClient client = new RavenClient(sentryDSN, getProxy());
 
-                // send the message to the sentry server
+                // is it an exception?
                 ThrowableInformation throwableInformation = loggingEvent.getThrowableInformation();
-                Throwable throwable = (throwableInformation == null ? null : throwableInformation.getThrowable());
-                client.logMessage(logMessage, timestamp, loggingClass, logLevel, culprit, throwable);
+
+                // send the message to the sentry server
+                if (throwableInformation == null){
+                    client.captureMessage(logMessage, timestamp, loggingClass, logLevel, culprit);
+                }else{
+                    client.captureException(logMessage, timestamp, loggingClass, logLevel, culprit, throwableInformation.getThrowable());
+                }
 
             } catch (Exception e) {
                 System.err.println(e);