Monitoring main documentation #3050
Conversation
| ## How do I get it? | ||
| ### Prerequisites | ||
| - Customers need to have an OpenTelemetry-compatible APM tool, which can be selected from the list of [supported vendors](https://opentelemetry.io/ecosystem/vendors/). <br> | ||
| - Customers need to be eligible for Spryker Monitoring Integration. |
… into otel-main-doc
|
|
||
| #### Hook | ||
| Hook is a function that executes a closure before and after method execution, providing a way to instrument code without modifying it directly. | ||
| When you execute your method, `pre` closure is executing and should open a span. After the method is executed, `post` closure is executed and should catch if method was executed successfully, add missing attributes (you can add a method return value, but we would not recommend it) and close a span. |
There was a problem hiding this comment.
Last line in this paragraph is not clear, rewrite
|
|
||
|
|
||
| ### Convention following | ||
| The current implementation follows [OpenTelemetry Semantic Conventions 1.30.0](https://opentelemetry.io/docs/specs/semconv/). |
There was a problem hiding this comment.
implementation of what?
| ``` | ||
|
|
||
| #### Metric details | ||
| The default metrics resolution is 60 seconds. All metrics can be split by telemetry-data-account. |
There was a problem hiding this comment.
What is telemetry-data-account?
| #### Metric details | ||
| The default metrics resolution is 60 seconds. All metrics can be split by telemetry-data-account. | ||
|
|
||
| ## How do I get it? |
| ## How do I get it? | ||
| ### Prerequisites | ||
| - Integrate an OpenTelemetry-compatible APM tool from the list of [supported vendors](https://opentelemetry.io/ecosystem/vendors/) | ||
| - Customers need to be eligible for Spryker Monitoring Integration |
There was a problem hiding this comment.
How do i become eligible?
| If you want to integrate manually, the following sections describe all steps of the scripts. | ||
|
|
||
| ### Install required packages | ||
| OpenTelemetry provides instrumentation via packages that can be installed to register hooks automatically. If you want to instrument something that is not covered in our code base but is required for you, you can try to install one of the packages listed at [Registry](https://opentelemetry.io/ecosystem/registry/?language=php) or from other sources. |
There was a problem hiding this comment.
What do you mean by something?
There was a problem hiding this comment.
Anything from 3rd party systems. E.g. Symfony packages
| ``` | ||
|
|
||
|
|
||
| After installation, you can call methods from Monitoring service and they will be translated to OpenTelemetry actions. Some of the methods are empty because those things have no direct implementation in Opentelemetry, like `\Spryker\Service\Opentelemetry\Plugin\OpentelemetryMonitoringExtensionPlugin::markStartTransaction()` as transaction will start anyway. |
There was a problem hiding this comment.
What do you mean by things?
| } | ||
| ``` | ||
|
|
||
| `\Spryker\Zed\Opentelemetry\OpentelemetryConfig::getExcludedSpans()` - allows you to exclude specific spans by name. You can use it to exclude autogenerated span that is not relevant for you, but excluding the directory itself is too much. |
There was a problem hiding this comment.
Why is it too much?
There was a problem hiding this comment.
By excluding directory you can exclude other spans that you still want to see in the traces
| } | ||
| ``` | ||
|
|
||
| `\Spryker\Zed\Opentelemetry\OpentelemetryConfig::getOutputDir()` - specifies in what directory you want to put generated hooks. Default value is `src/Generated/OpenTelemetry/Hooks/`. The classmap file will also be added into this directory. |
There was a problem hiding this comment.
exact name of the calssmap file?
| - grpc | ||
| - protobuf | ||
| ``` | ||
| Be advised that according to [extension README](https://github.com/open-telemetry/opentelemetry-php-instrumentation?tab=readme-ov-file#conflicting-extensions) `blackfire` extension can have a conflict with a `opentelemetry` one, so make sure that you are not using both in the same time. The `newrelic` extension also has conflict in Distributed Tracing headers mechanism, so using both extensions in the same time will cause broken traces in your APM. |
There was a problem hiding this comment.
what's opentelemetry one?
| @@ -0,0 +1,440 @@ | |||
| --- | |||
| title: OpenTelemetry instrumentation | |||
There was a problem hiding this comment.
For this whole document, replace we with what actually happens. Meaning, clearly define the subject of the action, such as the application or its components
|
|
||
| Please minimise amount of generated spans per request. OpenTelemetry documentation recommends to have no more than 1000 of them. So you can skip some spans via configuration that are not relevant to you. Don't be afraid, errors will be processed even if the method was not instrumented because Error Event will be attached to the root span. | ||
|
|
||
| Use sampling to not get a full trace every time. Please check configuration section for the reference. |
There was a problem hiding this comment.
Provide a link to the section where it's explained
|
|
||
| ## Changing a trace name | ||
|
|
||
| Trace name (or in our case a root span name) should show you what request or command was executed. By default it should include a HTTP method name with an URL for the WEB requests and command name for a command execution. |
There was a problem hiding this comment.
By default it should include
So you're not sure about what it includes?
There was a problem hiding this comment.
well, for CLI command it will not include HTTP things, but yeah the line can be changed
|
|
||
| You can define a service name via `\Spryker\Service\Monitoring\MonitoringService::setApplicationName()` or `\Spryker\Service\Opentelemetry\OpentelemetryService::setResourceName()`. | ||
|
|
||
| If you are using the `MonitoringService` and any method from it was executed, you will get a generated service name in any case. |
There was a problem hiding this comment.
This is not clear
There was a problem hiding this comment.
MonitoringService has a bunch of methods and each execution of any of it will trigger method that sets service name for monitoring tool
| If you are using the `MonitoringService` and any method from it was executed, you will get a generated service name in any case. | ||
|
|
||
| By default it looks like `APPLICATION-REGION_OR_STORE(application.env)`, where `APPLICATION` is a name of your application (ZED, YVES, GLUE, etc.), `REGION_OR_STORE` is a current store or region name that depends if your application works in Dynamic Store mode or not, and `application.env` is an env name from your deploy file. You can change any of those value via `MonitoringService` or change the name completely via `OpentelemetryService`. | ||
| If nothing was provided by services, OpenTelemetry integration will try to resolve a service name for you. |
There was a problem hiding this comment.
By nothing you mean no service name?
There was a problem hiding this comment.
yes. If no services was executed, no external service name was provided so we will try to generated it by ourself
PR labels
When the PR is ready for review, add a TW review needed label. This lets us keep track of PRs that need to be merged and merge them in time.
PR Description
Describe the context for your changes and the changes you've made.
Tickets
If changes are associated with a ticket, add a docs ticket here.
Checklist