Skip to content

Commit a9bd839

Browse files
EddeCCCEddeCCC
authored
Push 3.0.0 docs into master (#1858)
1 parent 9f97bf9 commit a9bd839

36 files changed

+1541
-1396
lines changed

‎inspectit-ocelot-documentation/docs/breaking-changes/breaking-changes.md‎

Lines changed: 163 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,168 @@
11
---
2-
id: Breaking Changes
2+
id: breaking-changes
33
title: Breaking Changes
44
---
55

6+
## Breaking changes in 3.0.0
7+
8+
### Full integration of native OpenTelemetry
9+
10+
Starting with the current release, inspectIT Ocelot fully migrates from OpenCensus to [OpenTelemetry](https://github.com/open-telemetry).
11+
OpenCensus has been completely replaced by OpenTelemetry within the **Java agent** as well as the **EUM server**.
12+
13+
### Updated metrics
14+
15+
#### Updated metric definition
16+
17+
By switching to OpenTelemetry metrics, the configuration model for [metrics](metrics/custom-metrics.md#metrics) and
18+
[views](metrics/custom-metrics.md#views) have changed. The metrics property `type` has been updated to `value-type`.
19+
Additionally, there is an option `instrument-type`, which defines the OpenTelemetry [instrument](https://opentelemetry.io/docs/languages/java/api/#meter)
20+
to use for recording the metric. Currently, we only support synchronous instruments like `COUNTER`, `UP_DOWN_COUNTER`,
21+
`GAUGE` or `HISTOGRAM`.
22+
23+
The aggregations for views have also changed. There is no more `COUNT` aggregation.
24+
Instead, you can use the `SUM` aggregation or the count field of the `HISTOGRAM` aggregation.
25+
For this reason, all default metrics containing a `COUNT` and `SUM` view have been updated with only one `HISTOGRAM` view,
26+
which still provides fields for count and sum values.
27+
There is also a new aggregation `EXPONENTIAL_HISTOGRAM`, which allows to record [base2 exponential buckets for histograms](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#base2-exponential-bucket-histogram-aggregation).
28+
Furthermore, the Java agent also supports the custom `SMOOTHED_AVERAGE` aggregation for views, which was only
29+
supported by the EUM server previously. There are some other new options, which are mentioned in the [views](metrics/custom-metrics.md#views) section.
30+
31+
Another change involves the metric output of inspectIT. Since the [metric data model](https://opentelemetry.io/docs/specs/otel/metrics/data-model/) has changed, it will probably be necessary
32+
to update dashboards or database configurations.
33+
34+
#### Updated metric names
35+
36+
With this version we are also updating our naming conventions for metrics. Instead of slashes `/`, we will start
37+
to use underscores `_`. Thus, metrics like `method/duration` have been renamed to `method_duration`.
38+
This involves all [self-monitoring](metrics/self-monitoring.md) metrics like `inspectit_self_instrumented_classes`,
39+
default [metrics recorders](metrics/metric-recorders.md) like `system_cpu_usage`
40+
and all metrics from the [default instrumentation](default-instrumentation/default-instrumentation.md) like `http_in_responsetime`.
41+
42+
Furthermore, OpenTelemetry does not use the term _tag_ for metric labels like OpenCensus, but instead they use _attributes_.
43+
Thus, we have updated several configuration options to comply with the OpenTelemetry language.
44+
Metric views no longer contain `tags`, but `attributes`. There are no _common tags_, but _common attributes_ and so on.
45+
However, sometimes we still refer to tags, e.g. `tag-guard` or `data-tags` in rules.
46+
Basically, tags and attributes reference the same concept of data labeling.
47+
48+
### InfluxDB exporter removed
49+
50+
Since the previous InfluxDB exporter was specifically designed for OpenCensus,
51+
due to the migration to OpenTelemetry the exporter was fully removed. Please use the other exporters instead.
52+
53+
### Migration guide for 3.0.0
54+
55+
#### 1. Update configuration
56+
57+
##### Metric names in rules
58+
59+
All default metric names have been updated and use underscores `_` instead of slashes `/`.
60+
Thus, if such metrics are referenced inside a rule, the rule has to be updated. Note that the entire default instrumentation
61+
has already been updated to use the new metric names.
62+
63+
```yaml
64+
inspectit.instrumentation.rules:
65+
r_example:
66+
exit:
67+
my-value:
68+
# ...
69+
metrics:
70+
http_in_responsetime: # previously http/in/responsetime
71+
value: my-value
72+
73+
```
74+
75+
##### Common attributes
76+
77+
Common attributes (previously common tags) are no longer configured via `inspectit.tags`, but
78+
`inspectit.attributes`. For example:
79+
80+
```properties
81+
inspectit.attributes.extra.region=us-west-1
82+
inspectit.attributes.extra.stage=preprod
83+
inspectit.attributes.providers.environment.enabled=true
84+
```
85+
86+
##### Tracing
87+
88+
Some tracing options have been renamed as well:
89+
90+
```yaml
91+
inspectit:
92+
tracing:
93+
add-metric-attributes: true # previously add-metric-tags
94+
add-common-attributes: true # previously add-common-tags
95+
```
96+
97+
##### Tag-Guard
98+
99+
Some Tag-Guard options have been renamed as well:
100+
101+
```yaml
102+
inspectit.metrics:
103+
tag-guard:
104+
max-values-per-attribute: 1000 # previously max-values-per-tag
105+
max-values-per-attribute-by-metric: # previously max-values-per-tag-by-measure
106+
my_metric: 200
107+
```
108+
109+
##### Data propagation
110+
111+
The propagation behaviour of data keys `inspectit.instrumentation.data` no longer contains the property `is-tag`.
112+
Inside OpenTelemetry baggage (previously OpenCensus TagContext) all data is usable for metrics or traces and
113+
can be propagated if the data key was properly configured.
114+
115+
#### 2. Update metric definitions
116+
117+
The configuration model for metrics and views has slightly changed.
118+
Thus, metric definitions have to be updated. The option `type` has to be updated to `value-type` for all metrics.
119+
The value `LONG` and `DOUBLE` are still valid. If no `value-type` is specified, the metric will use `LONG` by default.
120+
Additionally, an `instrument-type` has to be specified. If no `instrument-type` is specified, the metric will
121+
use `GAUGE` by default. There is an official [guideline](https://opentelemetry.io/docs/specs/otel/metrics/supplementary-guidelines/) to help you to choose the proper instrument.
122+
123+
```yaml
124+
inspectit.metrics.definitions:
125+
my_metric: # previously my/metric (most likely)
126+
unit: ms
127+
value-type: DOUBLE # previously type
128+
instrument-type: HISTOGRAM # new property, by default GAUGE
129+
views:
130+
# ...
131+
```
132+
133+
Furthermore, the view configurations have to be updated as well. There is no longer any `COUNT` aggregation.
134+
Thus, if you have defined two views with `COUNT` and `SUM` aggregation previously, now you define one single
135+
`HISTOGRAM` view, which will also offer fields for count and sum values. If no aggregation is specified for a view,
136+
Additionally, the options involving attributes (previously tags) have been renamed to `attributes`
137+
and `with-common-attributes`. There are also some new view options, which are optional.
138+
139+
```yaml
140+
inspectit.metrics.definitions:
141+
my_metric:
142+
# ...
143+
views:
144+
my_metric: # previously two views: my/metric/count and my/metric/sum (most likely)
145+
aggregation: HISTOGRAM
146+
with-common-attributes: true # previously with-common-tags
147+
attributes: # previously tags
148+
my-attr: true
149+
```
150+
151+
#### 3. Replace InfluxDB exporter
152+
153+
Even tough inspectIT Ocelot does no longer offer a dedicated InfluxDB exporter, there a plenty other options to
154+
export metrics to InfluxDB.
155+
156+
First, there is a [Prometheus Input Plugin](https://github.com/influxdata/telegraf/blob/master/plugins/inputs/prometheus/README.md)
157+
for [Telegraf](https://github.com/influxdata/telegraf/tree/master), which is able to gather metrics from a Prometheus endpoint.
158+
You can enable the [Prometheus exporter](metrics/metric-exporters.md#prometheus-exporter) of inspectIT Ocelot and collect metrics via Telegraf from the configured endpoint.
159+
After that, Telegraf can further send the metrics to InfluxDB.
160+
161+
Another alternative would be to use the [InfluxDB Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/influxdbexporter/README.md)
162+
of the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib).
163+
You can export metrics via the [OTLP exporter](metrics/metric-exporters.md#otlp-exporter-metrics) to the OTel collector.
164+
After that, the collector will further send the metrics to InfluxDB.
165+
6166
## Breaking changes in 2.7.0
7167

8168
### Tags exporter was fully removed
@@ -12,7 +172,7 @@ The agent does no longer expose an API to read or write data tags. Furthermore,
12172
was removed for data keys.
13173

14174
The exchange of data tags with remote services - including browsers - is still possible via propagation
15-
of the [Baggage](instrumentation/data-propagation.md#baggage) header.
175+
of the [Baggage](instrumentation/data-propagation.md#http-baggage) header.
16176
Tags can still can be [stored for sessions](instrumentation/data-propagation.md#session-storage) by enabling `session-storage` for specific data keys.
17177

18178
### Configuration Server requires Java 21
@@ -445,7 +605,7 @@ inspectit:
445605

446606
As these definitions could be easily forgotten, we changed the default behaviour of data:
447607
It now does *not* propagate and is *not* used as a tag automatically. The exception hereby
448-
is (a) if the data is a [common tag](metrics/common-tags.md) or (b) the data is used as a tag in any
608+
is (a) if the data is a [common tag](metrics/common-attributes.md) or (b) the data is used as a tag in any
449609
[metric definition](metrics/custom-metrics.md). Common Tags default to JVM_LOCAL down propagation and being a tag.
450610
When a data_key is also used as a tag in a metric definition, it defaults to being a tag but the propagation is not affected.
451611
You can still freely override the behaviour by configuring the settings for your data under `inspectit.instrumentation.data`.

‎inspectit-ocelot-documentation/docs/configuration/opentelemetry-configuration.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
id: opentelemetry-configuration
3-
title: Using OpenTelemetry Library with inspectIT Ocelot
3+
title: Using OpenTelemetry with inspectIT Ocelot
44
sidebar_label: OpenTelemetry Configuration
55
---
66

77
If you plan to use the OpenTelemetry library in an application which will be instrumented later on with inspectIT Ocelot,
88
some special rules do apply.
9-
Following these rules will make sure that there are no run-time problems in your application.
9+
Following these rules will make sure that there are no runtime problems in your application.
1010
Furthermore, a correct configuration will make it possible to combine metrics and traces that you manually collect
1111
using the OpenTelemetry instrumentation library with the ones collected by the inspectIT Ocelot agent.
1212

@@ -43,4 +43,5 @@ using the OpenTelemetry instrumentation library with the ones collected by the i
4343

4444
It is important to state that the agent will *not* publish the OpenTelemetry classes to the bootstrap classloader
4545
if it is attached during runtime – even if the previously mentioned JVM argument is set!
46-
In this case, metrics and traces of *manual OpenTelemetry instrumentations* will *not* be collected by the inspectIT Ocelot agent.
46+
In this case, metrics and traces of *manual OpenTelemetry instrumentation* of the application will *not* be
47+
collected by the inspectIT Ocelot agent.

‎inspectit-ocelot-documentation/docs/configuration/plugin-configuration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ id: plugin-configuration
33
title: Plugin Configuration
44
---
55

6-
There are more OpenCensus exporters available than the ones we have included with inspectIT Ocelot.
6+
There are more exporters available than the ones we have included with inspectIT Ocelot.
77
This decision was made so that we can keep the size and amount of dependencies of the agent small.
88
For this reason, we introduced a plugin system allowing you to add and configure additional exporters.
99

@@ -37,4 +37,4 @@ inspectit:
3737

3838
some-other-plugin:
3939
something: ...
40-
```
40+
```

‎inspectit-ocelot-documentation/docs/enduser-monitoring/enduser-monitoring-server.md‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,28 @@
11
---
22
id: enduser-monitoring-server
3-
title: End User Monitoring with Ocelot
3+
title: End User Monitoring with inspectIT Ocelot
44
sidebar_label: Overview
55
---
66

7-
The inspectIT Ocelot EUM Server can be used to collect EUM data.
8-
The EUM server is completely stateless and can be used as a network separation component between the EUM agents and the monitoring backend.
7+
The inspectIT Ocelot EUM Server can be used to collect end user (real user) data via [OpenTelemetry](https://opentelemetry.io/docs/languages/java/).
8+
The EUM server is completely stateless and can be used as a network separation component between
9+
the EUM agents and the monitoring backend.
910

1011
![EUM Server Architecture](assets/eum-architecture.png)
1112

12-
# Collecting metrics
13+
# Collecting Metrics
1314

14-
The server can be used to collect metrics, produced by the [Akamai Boomerang](https://developer.akamai.com/tools/boomerang) EUM Javascript Agent, and calculate metrics based on this data and store them in a metric backend like [Prometheus](https://prometheus.io/) or [InfluxDB](https://www.influxdata.com/products/influxdb-overview/).
15+
The server can be used to collect metrics, produced by the [Akamai Boomerang](https://techdocs.akamai.com/mpulse-boomerang/docs/welcome-to-mpulse-boomerang)
16+
EUM JavaScript Agent and calculate metrics based on this data and store them in a metric backend like [Prometheus](https://prometheus.io/)
17+
or [InfluxDB](https://www.influxdata.com/products/influxdb-overview/).
1518

16-
For this purpose, [OpenCensus](https://github.com/census-instrumentation/opencensus-java) is used, which enables the server to use all existing metric exporter implementations of OpenCensus.
19+
# Collecting Traces
1720

18-
# Collecting traces
21+
The server also support collection of EUM traces, as it implements the [OpenTelemetry Tracing API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md).
22+
The collected traces are propagated to any registered trace exporter.
1923

20-
The server also support collection of EUM traces, as it implements the [OpenTelemetry Trace V1 API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md).
21-
The collected traces are propagated to the any registered trace exporter.
22-
23-
Currently, the EUM server supports only [Jaeger](https://www.jaegertracing.io/) as the trace exporter (using the [Protobuf via gRPC](https://www.jaegertracing.io/docs/1.16/apis/#protobuf-via-grpc-stable) API).
24+
Currently, the EUM server supports only [OLTP](https://opentelemetry.io/docs/specs/otlp/) as the trace exporter.
2425

2526
:::tip
26-
If you already use Boomerang to collect the EUM metrics, you can automatically collect traces by using the [Boomerang OpenTelemetry plugin](https://github.com/NovatecConsulting/boomerang-opentelemetry-plugin).
27+
If you already use Boomerang to collect the EUM metrics, you can automatically collect traces by using our self-made [Boomerang OpenTelemetry plugin](https://github.com/inspectIT/boomerang-opentelemetry-plugin).
2728
:::

0 commit comments

Comments
 (0)