From 7c1f3f9c08b362e112fe2fac29d9dd100d3abba5 Mon Sep 17 00:00:00 2001 From: Frank Koornstra Date: Wed, 11 Apr 2018 12:50:58 +0200 Subject: [PATCH] Update middleware section in readme --- README.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8307c46..da7197b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ This readme functions both as documentation and as a means to communicate the go - [x] Create messages and requests - [x] Create interface for synchronous and asynchronous clients - [x] Implement asynchronous client -- [ ] Create PSR-15 middleware +- [x] Create PSR-15 middleware - [ ] Create a PSR-6 cache wrapper - [ ] Create a PSR-18 HTTP client wrapper - [ ] Create a PSR-18 HTTP request factory wrapper @@ -67,11 +67,21 @@ $error = $error->onSystem(...)->inProcess(...); // Got it! ### Middleware -**DRAFT, IN PROGRESS** +To measure the response time and report errors (by catching exceptions), you can hook up the [PSR-15](https://www.php-fig.org/psr/psr-15/) compliant middleware to your application. + +#### Transaction + +The `TransactionMiddleware` will inject an `OpenTransaction` into the forwarded request under the attribute name `apm-transaction` (but you better reference to it using the constant `TransactionMiddleware::TRANSACTION_ATTRIBUTE`). + +You can add `Span`s and mark events to the `OpenTransaction` and when you give a response, the middleware will pick them up and send them along with the transaction to the APM server. This is one of the view objects that _is mutable_ so you don't have to replace the request attribute every time you change something. + +#### Error + +If you want to catch and report `Throwable`s to APM, also include the `ErrorMiddleware` in your middleware stack. It will catch any `Throwable` and try to make as much sense of it as possible. To give the error even more context, you can on inject `Context` object on instantiation of the middleware. It will use that as the base for building context. -To measure the response time and report errors (by catching exceptions), hook up the [PSR-15](https://www.php-fig.org/psr/psr-15/) compliant middleware to your application. +#### Combination -It will inject the transaction in the request under the parameter name `apm-transaction` so you can add information to it later. If you do, be aware that **it is immutable** so you need to replace it in the request. +Obviously the two middleware can be combined. The recommended way to do this is to wrap the `ErrorMiddlware` _inside_ the `TransactionMiddleware`. That way the error will correlated to the transaction and the transaction duration will be as realistic as possible, including the time it takes to report the error to the APM server for example. ### Caching