From cc756b7778e5b53182053f064bc5276b4d52393d Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Thu, 11 Apr 2024 00:44:14 +0000 Subject: [PATCH 1/7] document logs and metrics for quote service --- content/en/docs/demo/services/quote.md | 40 ++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index ce3157297668..fc57d7115226 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -92,8 +92,44 @@ $span->addEvent('Quote processed, response sent back', [ ## Metrics -TBD +In this demo, metrics are emitted by the batch trace and logs processors. The +metrics describe the internal state of the processor, such as number of exported +spans/logs, the queue limit and queue usage. + +This is enabled by setting the environment variable +`OTEL_PHP_INTERNAL_METRICS_ENABLED=true`. + +A manual metric is also emitted, which counts the number of quotes generated, +including attributes for the number of items and total cost. + +### Initializing metrics + +To generate metrics, we need to create an instrument such as a counter, gauge or +histogram. In this example, we retrieve a meter from the globally configured +Meter Provider, and use it to create a counter: + +```php +$counter = Globals::meterProvider() + ->getMeter('my-meter') + ->createCounter('my-counter'); +``` + +Metrics will accumulate, and be exported periodically based on the value +configured in `OTEL_METRIC_EXPORT_INTERVAL`. + +### Generate metrics + +An instrument provides a method to record a new value against it. In this +example, we can `add` values to the counter: + +```php +$counter->add(2); +``` ## Logs -TBD +The quote service emits a log message after a quote is calculated. The Monolog +logging package is configured with a +[Logs Bridge](docs/concepts/signals/logs/#log-appender--bridge) which converts +Monolog logs into the OpenTelemetry format, and sends them to the configured +OpenTelemetry Logger. From beebb6d4732fb7a8604c9b0f6440ff7c382c53d6 Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Thu, 11 Apr 2024 01:09:46 +0000 Subject: [PATCH 2/7] fix link --- content/en/docs/demo/services/quote.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index fc57d7115226..bc5485927125 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -130,6 +130,6 @@ $counter->add(2); The quote service emits a log message after a quote is calculated. The Monolog logging package is configured with a -[Logs Bridge](docs/concepts/signals/logs/#log-appender--bridge) which converts -Monolog logs into the OpenTelemetry format, and sends them to the configured -OpenTelemetry Logger. +[Logs Bridge](/docs/concepts/signals/logs/#log-appender--bridge) which converts +Monolog logs into the OpenTelemetry format, and sends them to the globally +configured OpenTelemetry Logger. From 5f1d9047df3de33ff3b85015baaf95cede87b4ef Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Thu, 11 Apr 2024 11:35:55 +1000 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> --- content/en/docs/demo/services/quote.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index bc5485927125..5761edfcb830 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -94,9 +94,9 @@ $span->addEvent('Quote processed, response sent back', [ In this demo, metrics are emitted by the batch trace and logs processors. The metrics describe the internal state of the processor, such as number of exported -spans/logs, the queue limit and queue usage. +spans/logs, the queue limit, and queue usage. -This is enabled by setting the environment variable +You can enable metrics by setting the environment variable `OTEL_PHP_INTERNAL_METRICS_ENABLED=true`. A manual metric is also emitted, which counts the number of quotes generated, @@ -104,9 +104,9 @@ including attributes for the number of items and total cost. ### Initializing metrics -To generate metrics, we need to create an instrument such as a counter, gauge or -histogram. In this example, we retrieve a meter from the globally configured -Meter Provider, and use it to create a counter: +To generate metrics, you need to create an instrument such as a counter, gauge, or +histogram. The following example retrieves a meter from the globally configured +Meter Provider and uses it to create a counter: ```php $counter = Globals::meterProvider() @@ -114,13 +114,13 @@ $counter = Globals::meterProvider() ->createCounter('my-counter'); ``` -Metrics will accumulate, and be exported periodically based on the value +Metrics accumulate and are exported periodically based on the value configured in `OTEL_METRIC_EXPORT_INTERVAL`. ### Generate metrics -An instrument provides a method to record a new value against it. In this -example, we can `add` values to the counter: +An instrument provides a method to record a new value against it. This +example shows how to `add` values to the counter: ```php $counter->add(2); From 8b0ccaf801db6c0561932a2788fe9e613cc95930 Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Thu, 11 Apr 2024 01:37:33 +0000 Subject: [PATCH 4/7] fix formatting --- content/en/docs/demo/services/quote.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index 5761edfcb830..363f1cf42bd5 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -104,9 +104,9 @@ including attributes for the number of items and total cost. ### Initializing metrics -To generate metrics, you need to create an instrument such as a counter, gauge, or -histogram. The following example retrieves a meter from the globally configured -Meter Provider and uses it to create a counter: +To generate metrics, you need to create an instrument such as a counter, gauge, +or histogram. The following example retrieves a meter from the globally +configured Meter Provider and uses it to create a counter: ```php $counter = Globals::meterProvider() @@ -114,13 +114,13 @@ $counter = Globals::meterProvider() ->createCounter('my-counter'); ``` -Metrics accumulate and are exported periodically based on the value -configured in `OTEL_METRIC_EXPORT_INTERVAL`. +Metrics accumulate and are exported periodically based on the value configured +in `OTEL_METRIC_EXPORT_INTERVAL`. ### Generate metrics -An instrument provides a method to record a new value against it. This -example shows how to `add` values to the counter: +An instrument provides a method to record a new value against it. This example +shows how to `add` values to the counter: ```php $counter->add(2); From 6cfbe0c15a29ead04c96fd92153e269d77f540b2 Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Thu, 11 Apr 2024 23:52:16 +0000 Subject: [PATCH 5/7] rework generic doco --- content/en/docs/demo/services/quote.md | 28 +++++++++----------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index 363f1cf42bd5..f572f2df3674 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -102,34 +102,24 @@ You can enable metrics by setting the environment variable A manual metric is also emitted, which counts the number of quotes generated, including attributes for the number of items and total cost. -### Initializing metrics - -To generate metrics, you need to create an instrument such as a counter, gauge, -or histogram. The following example retrieves a meter from the globally -configured Meter Provider and uses it to create a counter: +A counter is created from the globally configured Meter Provider, and is +incremented each time a quote is generated: ```php -$counter = Globals::meterProvider() - ->getMeter('my-meter') - ->createCounter('my-counter'); +static $counter; +$counter ??= Globals::meterProvider() + ->getMeter('quotes') + ->createCounter('quotes', 'quotes', 'number of quotes calculated'); +$counter->add(1, ['number_of_items' => $numberOfItems]); ``` Metrics accumulate and are exported periodically based on the value configured in `OTEL_METRIC_EXPORT_INTERVAL`. -### Generate metrics - -An instrument provides a method to record a new value against it. This example -shows how to `add` values to the counter: - -```php -$counter->add(2); -``` - ## Logs The quote service emits a log message after a quote is calculated. The Monolog logging package is configured with a [Logs Bridge](/docs/concepts/signals/logs/#log-appender--bridge) which converts -Monolog logs into the OpenTelemetry format, and sends them to the globally -configured OpenTelemetry Logger. +Monolog logs into the OpenTelemetry format. Logs sent to this logger will be +exported via the globally configured OpenTelemetry logger. From a53f8b9ab7ef0616e6783884f9de83d9ffb24139 Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Fri, 12 Apr 2024 21:19:38 +1000 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Fabrizio Ferri-Benedetti --- content/en/docs/demo/services/quote.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index f572f2df3674..0726ac331e02 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -94,10 +94,10 @@ $span->addEvent('Quote processed, response sent back', [ In this demo, metrics are emitted by the batch trace and logs processors. The metrics describe the internal state of the processor, such as number of exported -spans/logs, the queue limit, and queue usage. +spans or logs, the queue limit, and queue usage. You can enable metrics by setting the environment variable -`OTEL_PHP_INTERNAL_METRICS_ENABLED=true`. +`OTEL_PHP_INTERNAL_METRICS_ENABLED` to `true`. A manual metric is also emitted, which counts the number of quotes generated, including attributes for the number of items and total cost. From dbe4cc1946a668af637597ea07f8b222db2b6eec Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Fri, 12 Apr 2024 11:21:46 +0000 Subject: [PATCH 7/7] update attribute wording --- content/en/docs/demo/services/quote.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index 0726ac331e02..5d04345e8e41 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -100,7 +100,7 @@ You can enable metrics by setting the environment variable `OTEL_PHP_INTERNAL_METRICS_ENABLED` to `true`. A manual metric is also emitted, which counts the number of quotes generated, -including attributes for the number of items and total cost. +including an attribute for the number of items. A counter is created from the globally configured Meter Provider, and is incremented each time a quote is generated: