provided usage description

Author: philkra

README.md

@@ -3,36 +3,28 @@
 Transform your application logs to structured logs that comply with the [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html).
 In combination with [filebeat](https://www.elastic.co/products/beats/filebeat) you can send your logs directly to Elasticsearch and leverage [Kibana's Logs UI](https://www.elastic.co/guide/en/infrastructure/guide/current/logs-ui-overview.html) to inspect all logs in one single place.
 This library allows you to provide more observability for your PHP applications as can e.g. corrolate your logs with e.g. APM traces.
+See [ecs-logging](https://github.com/elastic/ecs-logging) for other ECS logging libraries and more resources about ECS & logging.
 
-## Usage
-
-Please note that the major version of this library is compatible with the major version of ECS.
-
-### Install
-
+## Install
 ```
 composer require elastic/ecs-logging-php
 ```
 
-### Monolog Formater
-```php
-use Monolog\Logger;
-use Monolog\Handler\StreamHandler;
-use Elastic\Monolog\Formatter\ElasticCommonSchemaFormatter;
-
-$logger = new Logger('my_ecs_logger');
-$formatter = new ElasticCommonSchemaFormatter();
-$handler = new StreamHandler('<path-to-log-dir>/application.json', Logger::INFO);
-$handler->setFormatter($formatter);
-$logger->pushHandler($handler);
-```
+## Examples and Usage
+* [Monolog](https://github.com/elastic/ecs-logging-php/blob/master/docs/Monolog/README.md)
 
 ## Library Support
-Currently only [Monolog:2.*](https://github.com/Seldaek/monolog) is supported.
+* Currently only [Monolog:2.*](https://github.com/Seldaek/monolog) is supported.
+* The major version of this library is compatible with the major version of ECS.
 
 ## References
 * Introduction to ECS [blog post](https://www.elastic.co/blog/introducing-the-elastic-common-schema).
 * Logs UI [blog post](https://www.elastic.co/blog/infrastructure-and-logs-ui-new-ways-for-ops-to-interact-with-elasticsearch).
 
+## Test
+```
+composer test
+```
+
 ## License
 This software is licensed under the [Apache 2 license](https://github.com/elastic/ecs-logging-php/blob/master/LICENSE).

docs/Monolog/README.md

@@ -0,0 +1,27 @@
+# Monolog
+
+## Initialize the Formatter
+```php
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+use Elastic\Monolog\Formatter\ElasticCommonSchemaFormatter;
+
+$logger = new Logger('my_ecs_logger');
+$formatter = new ElasticCommonSchemaFormatter();
+$handler = new StreamHandler('<path-to-log-dir>/application.json', Logger::INFO);
+$handler->setFormatter($formatter);
+$logger->pushHandler($handler);
+```
+
+## Log Throwable's
+In order to enrich your error log message with [`Throwable`](https://www.php.net/manual/en/class.throwable.php)'s data, you need to pass
+the _caught_ exception or error with the key `throwable` in the context of the log message.
+```php
+$logger->error($t->getMessage(), ['throwable' => $t]);
+```
+
+## Trace Context
+You can add a trace context to every log message by leveraging the `trace` key in contex to pass a trace Id.
+```php
+$logger->notice('I am a log message with a trace id, so you can do awesome things in the Logs UI', ['trace' => $traceId]);
+```