MINOR: Moved docs around and linked from README.

phptek · Mar 2, 2017 · bc6b8da · bc6b8da
1 parent 91880b5
commit bc6b8da
Show file tree

Hide file tree

Showing 3 changed files with 80 additions and 63 deletions.
diff --git a/README.md b/README.md
@@ -26,74 +26,15 @@ Configure your application or site with the Sentry DSN into your project's YML c
 
     SilverStripeSentry\Adaptor\SentryClientAdaptor:
       opts:
-        dsn: <sentry_dsn_configured_in_sentry_itself>
+        # Example DSN only. Obviously you'll need to setup your own Sentry "Project"
+        dsn: http://deacdf9dfedb24ccdce1b90017b39dca:deacdf9dfedb24ccdce1b90017b39dca@sentry.mydomain.nz/44
 
 ## Usage
 
-Sentry is normally setup once in your _config.php file as follows:
-
-### Basic
+Sentry is normally setup once in your project's `_config.php` as follows, but see the [usage docs](docs/usage.md) for more detail and options.
 
     SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory(), SS_Log::ERR, '<=');
 
-### Specify an environment
-
-If an environment is not specified, the default is to use the return value of `Director::get_environment_type()`.
-
-    $config = ['env' => 'live'];
-    SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory($config), SS_Log::ERR, '<=');
-
-### Specify additional tags to filter-on in the Sentry UI
-
-Sentry allows for custom key-value pairs to be sent as "tags". This then allows for
-messages to be filtered via the Sentry UI.
-
-    $config = [
-        'env' => 'live',
-        'tags' = [
-            'Unique-ID' => $someObject->getFooID()
-        ]
-    ];
-    SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory($config), SS_Log::ERR, '<=');
-
-### Specify additional data to appear in the Sentry UI
-
-Once a message is selected within the Sentry UI, additional, arbitrary data can be displayed 
-to further help with debugging.
-
-    $config = [
-        'env' => 'live',
-        'tags' => [
-            'Unique-ID' => $someObject->getFooID()
-        ],
-        extra => [
-            'Moon-Phase' => 'Full',
-            'Tummy-Status' => 'Empty',
-            'Cats' => 'Are furry'
-        ]
-    ];
-    SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory($config), SS_Log::ERR, '<=');
-
-### Additional data at runtime
-
-Setting-up everything you want think you want to send, all from one spot is somewhat inflexible. Using the following however,
-we can set additional, arbitrary and context-specific data to be sent to Sentry via calls to SS_Log::log and its optional
-3rd parameter. You can then call SS_Log::log() in your project's customised Exception classes.
-
-In order to inject additional data into a message at runtime, simply pass a 2-dimensional array
-to the 3rd parameter of `SS_Log::log()` who's first key is "extra" and who's value is an array of values
-comprising the data you wish to send:
-
-    SS_Log::log('Help, my curry is too hot. I only asked for mild.', SS_Log::ERR, ['extra' => ['toilet' => 'now']]);
-
 ## TODO
 
-A rough plan of features to implement. These will be contingent on those Sentry features
-available to us in the default Raven_Client. However, there's nothing stopping us, stop-gapping what Raven_Client 
-doesn't provide (e.g. "fingerprinting") with our own customised curl calls. These could be routed through
-logic in Raven's Raven_CurlHandler class.
-
-* [fingerprinting](https://docs.sentry.io/learn/rollups/#customize-grouping-with-fingerprints)
-* [breadcrumbs](https://docs.sentry.io/learn/breadcrumbs/)
-* Add feature-checking routine for features against the instance of Sentry being called
-* Add release data ([see here](https://docs.sentry.io/clients/php/config/))
+See the [TODO docs](docs/todo.md) for more.
diff --git a/docs/todo.md b/docs/todo.md
@@ -0,0 +1,11 @@
+# TODO
+
+A rough plan of features to implement. These will be contingent on those Sentry features
+available to us in the default Raven_Client. However, there's nothing stopping us, stop-gapping what Raven_Client 
+doesn't provide (e.g. "fingerprinting") with our own customised curl calls. These could be routed through
+logic in Raven's Raven_CurlHandler class.
+
+* [fingerprinting](https://docs.sentry.io/learn/rollups/#customize-grouping-with-fingerprints)
+* [breadcrumbs](https://docs.sentry.io/learn/breadcrumbs/)
+* Add feature-checking routine for features against the instance of Sentry being called
+* Add release data ([see here](https://docs.sentry.io/clients/php/config/))
diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,65 @@
+# Usage
+
+In your project's `_config.php`, set one of the following, depending on your
+use-case.
+
+## Basic
+
+    SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory(), SS_Log::ERR, '<=');
+
+## Set an environment
+
+If an environment is not specified, the default is to use the return value of `Director::get_environment_type()`.
+
+    $config = ['env' => 'live'];
+    SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory($config), SS_Log::ERR, '<=');
+
+## Set tags
+
+Sentry allows for custom key-value pairs to be recorded against each message that it is sent.
+These are known as "tags", and they allow for fine-grained grouping and filtering of messages via the Sentry UI.
+
+Note: It makes no sense to send hugely varying data in a tag. If it's unlikely that a tag you
+wish to send, is ever going to be repeated, don't send it as a tag. Look at using the "Extras" feature (described below)
+instead.
+
+    $config = [
+        'env' => 'live',
+        'tags' = [
+            'Unique-ID' => 44
+        ]
+    ];
+    SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory($config), SS_Log::ERR, '<=');
+
+## Set extras
+
+Once a message is selected within the Sentry UI, additional, arbitrary data can be displayed 
+to further help with debugging. You can opt to send this as a consistent "baked-in" set of values
+from within `_config.php` or at runtime, via passing the optional 3rd parameter to `SS_Log::log()`.
+
+### Via _config.php
+
+    $config = [
+        'env' => 'live',
+        'tags' => [
+            'Unique-ID' => 44
+        ],
+        extra => [
+            'Moon-Phase' => 'Full',
+            'Tummy-Status' => 'Empty',
+            'Cats' => 'Are furry'
+        ]
+    ];
+    SS_Log::add_writer(\SilverStripeSentry\SentryLogWriter::factory($config), SS_Log::ERR, '<=');
+
+### Via SS_Log::log()
+
+Setting-up everything you want think you want to send, all from one spot in `_config.phjp` is somewhat inflexible. Using the following however,
+we can set additional, arbitrary and context-specific data to be sent to Sentry via calls to SS_Log::log and its optional
+3rd parameter. You can then call SS_Log::log() in your project's customised Exception classes.
+
+In order to inject additional data into a message at runtime, simply pass a 2-dimensional array
+to the 3rd parameter of `SS_Log::log()` who's first key is "extra" and who's value is an array of values
+comprising the data you wish to send:
+
+    SS_Log::log('Help, my curry is too hot. I only asked for mild.', SS_Log::ERR, ['extra' => ['toilet' => 'now']]);