diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/breaking-changes/breaking-changes.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/breaking-changes/breaking-changes.md new file mode 100644 index 0000000000..3fb406ccc6 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/breaking-changes/breaking-changes.md @@ -0,0 +1,459 @@ +--- +id: version-2.6.2-Breaking Changes +title: Breaking Changes +original_id: Breaking Changes +--- + +## Breaking changes in 2.6.0 + +### Git-Staging of Agent Mappings + +In addition to all agent configurations, the agent mappings will be staged as well now. +Thus, it is possible to keep a version history of the agent mappings. +There have been changed to the agent-mappings-page in the configuration server. + +Furthermore, the source branch of the entire agent mappings configuration is adjustable. +Now you can choose, whether the agent mappings configuration should be used from `WORKSPACE` (like previously) +or from `LIVE` (promoted changes). +You can find more information [here](config-server/agent-mappings.md#Git-Staging). + +### Tag-Guard + +The Tag-Guard allows to limit the amount of tag values, which will be exported for a specific tag of a specific measure. +This may help to prevent high cardinalities in your time series database. + +The recorded tag values for each tag per measure of an agent will be stored inside a local JSON file. This file serves +as the tag-guard-database and helps to check, if tag values exceeded their limit. +If a tag value has exceeded its limit, the agent health will change to `ERROR`. Therefore, the configured limit should be +evaluated carefully. +You can find more information [here](metrics/tag-guard.md). + + +## Breaking changes in 2.4.0 + +### Sampling adjusted + +Moving from OpenCensus to OpenTelemetry, the [global sampling](tracing/tracing.md#global-sampling-rate) and [rule-based sampling](instrumentation/rules.md#trace-sampling) has slightly changed. +We now offer three different sampling modes that can be set to `inspectit.tracing.sample-mode` and under the `tracing.sample-mode` property in individual rules. + +:::important +We do not expect any breaking change, but we want to promote this. +::: + +In case you encounter issues with sampling, the following explanation may help you resolving your issues. +Previously, a mix of the [ProbabilitySampler](https://github.com/census-instrumentation/opencensus-java/blob/master/api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java) +and [SpanBuilderImpl](https://github.com/census-instrumentation/opencensus-java/blob/52f38e48e2ac6cb65e28dcd97b4f7e9650357bba/impl_core/src/main/java/io/opencensus/implcore/trace/SpanBuilderImpl.java#L71) +from OpenCensus was used. This resulted in *child* spans being sampled if the parent span was not sampled but a sample probability was specified for a rule. +It may be the case that you need to set the `sample-mode` in your individual rules in case `PARENT_BASED` is set globally and parent spans would not be sampled, but individual child spans should be sampled. + +| Sample mode | Description | +|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `PARENT_BASED` (default for `inspectit.tracing.sample-mode`) | The setting of the `sample-probability` only has an effect if **no sampling decision** has been made yet. If a parent span has already decided that a trace is sampled or not sampled, this decision will continue to be used. This means that, for example, a method within a trace that has already been started will always be recorded, even if the sample setting has been set to `0`. This also applies to the opposite case where a span has decided not to sample and the sampling rate has been set to `1`. In this case the method will **not** be recorded!. See also the [official documentation of OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#parentbased). | +| `TRACE_ID_RATIO_BASED` | The sampling decision is made for each span, regardless of the parent span's sampling decision, see also the [official documentation of OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#parentbased). | +| `HYBRID_PARENT_TRACE_ID_RATIO_BASED` (default for `inspectit.instrumentation.rules.[name-of-rule].tracing.sample-mode`) | The span is sampled if the parent span has been sampled, otherwise applies a [TraceIdRatioBasedSampler](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampler). This behavior is similar to the previously used [ProbabilitySampler](https://github.com/census-instrumentation/opencensus-java/blob/master/api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java) from OpenCensus. | + +## Breaking changes in 2.0.0 + +### Integration of the OpenTelemetry OpenCensus Shim + +Starting with the current release, inspectIT Ocelot migrates from OpenCensus to [OpenTelemetry](https://github.com/open-telemetry). As a first step, we include the [OpenTelemetry OpenCensus Shim](https://github.com/open-telemetry/opentelemetry-java/tree/main/opencensus-shim). inspectIT Ocelot still uses and supports the [OpenCensus-API](https://opencensus.io/quickstart/java/), but the exporter implementations of OpenTelemetry are used. + +### AutoTracing currently not available + +Due to the migration from OpenCensus to OpenTelemetry, the agent's AutoTracing feature is currently **not** available. +The AutoTracing feature will be available again in the next release of the inspectIT Ocelot agent. + +### Removed the tag `service-name` from all exporters + +Due to the migration to OpenTelemetry, the tag `service-name` was removed from all exporters. Analogous to this tag, the tag `inspectit.service-name` can now be set globally for all exporters. + +### Updated and removed exporter + +#### Removed `OpenCensusAgentExporter` + +Due to the migration from OpenCensus to OpenTelemetry, the `OpenCensus Agent Exporter` (for metrics and traces) has been removed and will not be supported in the future. + +#### Added `OTLPMetricsExporter` and `OTLPTraceExporter` + +Due to the migration to OpenTelemetry, inspectIT Ocelot now supports OpenTelemetry Protocol (OTLP) exporter for metrics and tracing. + +#### Exporter property `url` and `grpc` replaced by `endpoint` + +Due to the migration to OpenTelemetry, we approach the naming of OpenTelemetry for the exporters' properties. For this, the previously used properties `url` and `grpc` are replaced by the property `endpoint`. The deprecated properties `url` and `grpc` are still supported in this release but will be removed in future releases. + +#### New property `protocol` for Jaeger and OTLP exporter + +This release introduces the property `protocol` for the Jaeger and OpenTelemetry Protocol (OTLP) exporter. In case for Jaeger, supported protocols are `http/thrift` and `grpc`. For OTLP, supported protocols are `grpc` and `http/protobuf`. + +## Breaking changes in 1.16.0 + +### Configuration sources only accept valid `YAML`, `JSON` (keys must be wrapped in double quotes) or `properties` notation + +As of version 1.16.0, the [configuration sources](configuration/configuration-sources.md) only accept valid `YAML`, `JSON` or `properties` notation. The "mix and match" of JSON and YAML should be avoided. For JSON, all keys need to be wrapped in double quotes. +Upgrading to version 1.16.0 may break your startup routines if the JSON passed as command line arguments is invalid. For example, the following code will **not** work anymore and cause an exception: + +```bash +# invalid JSON (keys not wrapped in double quotes) causes an exception + java -jar inspectit-ocelot-agent-1.16.0.jar 1337 '{inspectit:{service-name:"my-agent"}}' +``` +Instead, use valid JSON and wrap the keys in double quotes: + +```bash +# valid JSON (keys wrapped in double quotes) + java -jar inspectit-ocelot-agent-1.16.0.jar 1337 '{"inspectit":{"service-name":"my-agent"}}' +``` + +## Breaking changes in 1.15.2 + +There are no breaking changes for version 1.15.2. + +## Breaking changes in 1.15.1 + +There are no breaking changes for version 1.15.1. + + +## Breaking changes in 1.15.0 + +### New definition of exporters' enabled property + +Instead of a Boolean, the `enabled` property of exporters is now an enum with the values `DISABLED`, `ENABLED` and `IF_CONFIGURED` to express the behaviour of this property more clearly. +For now old configurations using `true` and `false` will still work and be converted to their equivalent new values `IF_CONFIGURED` and `DISABLED` respectively. +This conversion is however deprecated, so configurations should still be updated to the new values. + +### Prometheus exporter disabled by default + +By default, the Prometheus exporter is now disabled. +This was changed so the exporter's behaviour is in line with the behaviour of other exporters, i.e. it will not run without changing the default settings. +To enable the Prometheus exporter, set its `enabled` property to `ENABLED`. + +## Breaking changes in 1.14.0 + +There are no breaking changes for version 1.14.0. + +## Breaking changes in 1.13.0 + +There are no breaking changes for version 1.13.0. + +## Breaking changes in 1.12.2 + +There are no breaking changes for version 1.12.2. + +## Breaking changes in 1.12.1 + +There are no breaking changes for version 1.12.1. + +## Breaking changes in 1.12.0 + +There are no breaking changes for version 1.12.0. + +## Breaking changes in 1.11.1 + +There are no breaking changes for version 1.11.1. + +## Breaking changes in 1.11.0 + +There are no breaking changes for version 1.11.0. + + +## Breaking changes in 1.10.1 + +There are no breaking changes for version 1.10.1. + + +## Breaking changes in 1.10.0 + +There are no breaking changes for version 1.10.0. + + +## Breaking changes in 1.9.0 + +### Upgraded OpenTelemetry of the EUM Server + +The EUM server provides the functionality to receive OpenTelemetry spans and forward them to a tracing backend. + +Until now, an early alpha version of OpenTelemetry was used for this purpose, which has now been upgraded to the current, stable version. +As a result, spans from OpenTelemetry libraries older than version `0.9` are no longer compatible and can no longer be processed. + +This also means that third-party applications are no longer compatible with the EUM server that did not use OpenTelemetry in version `0.9` or higher, for example like the [Boomerang-OpenTelemetry plugin](https://github.com/NovatecConsulting/boomerang-opentelemetry-plugin) in version `0.7.0`. + +### Naming Changes of the `rt.bmr.*` Beacon Properties + +In the current release, the existing `rt.bmr` beacon parameter is parsed into new key-value pairs with the naming `rt.bmr.index`, where `index` represents the element's position in the beacon parameter. +These indices are changed to qualified names: + +| Deprecated Name | New Name | +| --- | --- | +|`rt.bmr.0`| `rt.bmr.startTime`| +|`rt.bmr.1`| `rt.bmr.responseEnd`| +|`rt.bmr.2`| `rt.bmr.responseStart`| +|`rt.bmr.3`| `rt.bmr.requestStart`| +|`rt.bmr.4`| `rt.bmr.connectEnd`| +|`rt.bmr.5`| `rt.bmr.secureConnectionStart`| +|`rt.bmr.6`| `rt.bmr.connectStart`| +|`rt.bmr.7`| `rt.bmr.respdomainLookupEndonseEnd`| +|`rt.bmr.8`| `rt.bmr.domainLookupStart`| +|`rt.bmr.9`| `rt.bmr.redirectEnd`| +|`rt.bmr.10`| `rt.bmr.redirectStart`| + +## Breaking changes in 1.8.1 + +There are no breaking changes for version 1.8.1. + + +## Breaking changes in 1.8 + +### Changing Capitalization of Self-Monitoring Metric Names + +In the current release, the capitalization of the name of the EUM server's self-monitoring metric for counting incoming beacons has been changed. +It was changed from `inspectit-eum_self_beacons_received_COUNT` to `inspectit_eum_self_beacons_received_count`, thus, it consists only of lowercase characters, now. + + +## Breaking changes in 1.7 + +There are no breaking changes for version 1.7. + + +## Breaking changes in 1.6.1 + +There are no breaking changes for version 1.6.1. + + +## Breaking changes in 1.6 + +There are no breaking changes for version 1.6. + + +## Breaking changes in 1.5 + +### Regex Replacement in the EUM-Server + +In the previous versions, it was possible to specify derived tags in the EUM-Server based +on a single regular expression extraction: + +```YAML +inspectit-eum-server: + tags: + beacon: + URL_USER_ERASED: + input: u + regex: "\\/user\\/\d+" + replacement: "\\/user\\/{id}" + keep-no-match: true +``` + +This configuration uses of the tag value `u`, replaces all user-IDs and stores the result in the tag `URL_USER_ERASED`. +While for backwards compatibility reasons this approach still is functional, it has been deprecated in favor of the new syntax: + +```YAML +inspectit-eum-server: + tags: + beacon: + URL_USER_ERASED: + input: u + replacements: + - regex: "\\/user\\/\d+" + replacement: "\\/user\\/{id}" + keep-no-match: true +``` + +This new syntax allows to specify a list of regular expressions to apply instead of a single one. +The EUM-Server will process all regular expressions in their order and will replace all matches within the input tag. +The `keep-no-match` property defines how to behave in case no match is found in the source tag for a given regex. +If `keep-no-match` is `false`, no tag value will be output in this case. If it is `true`, +the previous value will be used without performing any replacements. +Hereby the default value of `keep-no-match` has changed: it is now `true` instead of `false`. + + +## Breaking changes in 1.4 + +### Using Access Permissions in the Web UI + +The web interface of the configuration server now respects the access rights of the individual users. +Previously, every user who could log in had all rights and could therefore do everything. +However, this may cause problems for users who remain logged in during the upgrade. + +If the configuration server was recently upgraded to version 1.4 and active users exist, +it can happen that they are no longer able to access the web UI after the upgrade. +In this case the browser cache and cookies must be deleted. +Users should then be able to log on to and use the Web UI as usual. + + +## Breaking changes in 1.3.1 + +There are no breaking changes for version 1.3.1. + + +## Breaking changes in 1.3 + +### Changed Trace Attributes Behaviour + +In previous version it was possible to write [trace attributes](instrumentation/rules.md#adding-attributes) +without actually starting a span in the same method. In this case, attributes would be written to a parent method which was traced. +This could sometimes lead to a surprising behaviour and therefore has been removed. + +This behaviour can still be realized if desired via [data propagation](instrumentation/rules.md#data-propagation). + +### Reworked Default Agent Configuration + +The default configuration of the agent has completely been reworked. + +This means that in case your custom instrumentation is based on existing scopes, actions or rules it might stop working. +In order to fix this it is required to adapt your instrumentation to the new default configuration. + +### Changed Default Behaviour of the InfluxDB exporter + +The InfluxDB metrics exporter has been extended with an optimized handling of counter and sum metrics, which is now the default behaviour. +This new behaviour changes how data is written to InfluxDB, so your existing queries have to be adapted or reworked. + +It is still possible to use the previous handling of counters using the exporter's `counters-as-differences` option and setting it to `false`: + + inspectit: + exporters: + metrics: + influx: + counters-as-differences: false + +For more details have a look at the [InfluxDB exporter documentation](metrics/metric-exporters.md#influxdb-exporter). + + +## Breaking changes in 1.2.1 + +There are no breaking changes for version 1.2.1. + + +## Breaking changes in 1.2 + +There are no breaking changes for version 1.2. + + +## Breaking changes in 1.1 + +### Changed default data-propagation behaviour + +In previous versions data collected in [instrumentation rules](instrumentation/rules.md) could already be used without +explicitly defining it's propagation behaviour under `inspectit.instrumentation.data`. However, in this case the data +would be automatically down-propagated and used as a tag, which comes with a performance penalty. + +To avoid unnecessary propagation and usage as tag for e.g. temporary local data, the behaviour had to be explicitly defined: + +```yaml +inspectit: + instrumentation: + data: + temp_variable: {down-propagation: NONE, is-tag: false} +``` + +As these definitions could be easily forgotten, we changed the default behaviour of data: +It now does *not* propagate and is *not* used as a tag automatically. The exception hereby +is (a) if the data is a [common tag](metrics/common-tags.md) or (b) the data is used as a tag in any +[metric definition](metrics/custom-metrics.md). Common Tags default to JVM_LOCAL down propagation and being a tag. +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. +You can still freely override the behaviour by configuring the settings for your data under `inspectit.instrumentation.data`. +For details see the corresponding [documentation section](instrumentation/rules.md#defining-the-behaviour). + +This is a breaking change because your configurations might not work as expected anymore. +You now have to make sure that for each data, where you expect down-propagation to take place, you add a behaviour definition: + +```yaml +inspectit: + instrumentation: + data: + down_propagated_var: {down-propagation: JVM_LOCAL} +``` + +The change of the `is-tag` setting usually should not affect you, as it automatically picks up tags from the metrics definitions. + +### Changed metric collection configuration + +In previous versions Ocelot allowed the short notation in the configuration when defining the metrics collection. + +```yaml +#inspectit.instrumentation.rules is omitted here +example_rule: + #... + exit: + method_duration: + #action invocation here.... + + metrics: + '[method/duration]' : method_duration +``` + +This notation is now deprecated and has to be migrated to the explicit notation: + +```yaml +#inspectit.instrumentation.rules is omitted here +example_rule: + #... + exit: + method_duration: + #action invocation here.... + method_name: + #action invocation here.... + + metrics: + '[method/duration]': + value: method_duration + constant-tags: + action: checkout + data-tags: + method_name: method_name +``` + +This is a breaking change because your configurations might not work as expected anymore. +In previous versions tags were automatically picked up from the tag context at the moment of the metric recording. +The new notation allows explicit and flexible definition of constant and data tags to be collected with their associated values. +Staying with the short notation means that metric recording will only include addition of the common tags and values, thus most likely breaking the expected behavior. + +More information about the new notation can be found in the [collecting metrics](instrumentation/rules.md#collecting-metrics) section. + +### Changed EUM server tag configuration + +In previous versions of the EUM Server, tags derived from beacon values were specified as follows: + +```yaml +inspectit-eum-server: + tags: + beacon: + URL: u +``` + +This has been extended with the possibility to perform regex replacements, therefore the equivalent configuration now looks as follows: + +```yaml +inspectit-eum-server: + tags: + beacon: + URL: + input: u +``` + +For the details on how to perform regex replacements see the [EUM server documentation](enduser-monitoring/enduser-monitoring-server.md#tags-definition). + + +## Breaking changes in 1.0 + +There are no breaking changes for version 1.0. + + +## Breaking changes in 0.6 + +There are no breaking changes for version 0.6. + + +## Breaking changes in 0.5 + +This section discusses the changes that you need to be aware of when migrating your inspectIT Ocelot components to version 0.5. + +### Change of the configuration server's configuration prefix + +Until now, all components used the configuration prefix `inspectit` for the inspectIT Ocelot specific configuration settings. +This often led to confusion because, especially in examples, it was not clear to which component a particular setting belonged. +To avoid confusion between the configurations of different components the configuration prefix of the configuration server has been changed to `inspectit-config-server`. + +The configuration server will not load the configuration if it is still located under the `inspectit` prefix. + + +## Breaking changes in 0.4 + +There are no breaking changes for version 0.4. diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/agent-mappings.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/agent-mappings.md new file mode 100644 index 0000000000..6fab5fec1c --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/agent-mappings.md @@ -0,0 +1,96 @@ +--- +id: version-2.6.2-agent-mappings +title: Agent Mappings +original_id: agent-mappings +--- + +Agent mappings are used to determine which agent receives which configuration. Here, individual files or specific +folders can be defined, which serve as the basis for the resulting configuration. +Furthermore, you can specify which branch (`WORKSPACE` or `LIVE`) the mapping should use to obtain the configuration files. + +It's important to note that the first matching agent mapping will be used to determine which configuration is shipped to an agent. +Additional agent mappings which may also match the attributes list sent by an agent will be ignored. +See section [HTTP-based Configuration](configuration/external-configuration-sources.md#http-based-configuration) for +information on how to specify which attributes will be sent by an agent. + +An agent mapping consists of the following properties: + +| Property | Default | Note | +| --- | --- | --- | +| `name` | - | The name of the agent mapping. | +| `sources` | `[]` | A list of paths. All configuration files matching this list (Directories are resolved recursively) will be merged together and returned to matching agents. | +| `attributes` | `{}` | A map of attributes. This map is used to determine whether an agent will match this agent mapping, thus, get its configuration. | +| `sourceBranch` | `WORKSPACE` | Defines which branch is used as source for the configuration files. Supported values are: `WORKSPACE`, `LIVE` | + + +The configuration server is shipped with a default agent mapping. +This default agent mapping maps each agent to each configuration file of the `workspace` branch. + +```YAML +- name: "Default Mapping" + sources: + - "/" + attributes: + service: ".*" + sourceBranch: "WORKSPACE" +``` + +## Git Staging + +:::tip +You can find more detailed information about file staging and promotion [here](config-server/files-staging.md). +::: + +Since the version `2.6.0` the configuration for the agent mappings itself will also be included into the git staging. For all agent mappings +the configuration is stored in one file. After one or several agent mappings have been edited, the changes will also +appear on the promotion page. The promotion of the agent mappings configuration works directly like the promotion of agent configuration files. + +Additionally, it is possible to select a source branch (`WORKSPACE` or `LIVE`) for the agent mappings configuration itself. +This will determine, whether changes in the agent mappings should be applied directly or only after the promotion of the +agent mappings configuration. + +:::important +The source branch for the agent mappings configuration will **not affect** the defined `sourceBranch` in each **individual agent mapping**! +The `sourceBranch` property of an individual agent mapping determines, which branch should be used for the agent configuration files. +::: + +![Different Source Branches on Agent Mappings Page](assets/agent_mappings_source_branch.png) + +You can define, which source branch should be used at start-up for the agent mappings +in the application properties of the configuration server: + +```YAML +inspectit-config-server: + initial-agent-mappings-source-branch: WORKSPACE +``` + +## Example Agent Mappings + +### Example 1 + +The following agent mapping will deliver all promoted configuration files located in the directory `/common` and `/europe/west` to all agents whose `region` attributes is equal to `eu-west`. + +```YAML +- name: "Example Mapping 1" + sources: + - "/common" + - "/europe/west" + attributes: + service: ".*" + region: "eu-west" + sourceBranch: "LIVE" +``` + +### Example 2 + +The following agent mapping will deliver all configuration files located in the directory `/common` and the specific file `/special/customer-service.yml` of the `workspace` branch to all agents whose `service` attributes is equal to `customer-service`. + +```YAML +- name: "Example Mapping 2" + sources: + - "/common" + - "/special/customer-service.yml" + attributes: + service: "customer-service" + sourceBranch: "WORKSPACE" +``` diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/config-docs.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/config-docs.md new file mode 100644 index 0000000000..19c1c4afc2 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/config-docs.md @@ -0,0 +1,116 @@ +--- +id: version-2.6.2-config-docs +title: Configuration Docs +original_id: config-docs +--- + +Since version `1.15.0` the inspectIT Ocelot configuration server provides the option to look at documentation for +instrumentation objects, i.e. scopes, rules and actions, as well as metrics from the perspective of a selected agent mapping. + +## Using existing Configuration Docs + +To open the sidebar for the documentation, click on the `Configuration Docs`-button to the right of the configuration editor. + +![Picture of opened Configuration Docs view](assets/config-docs-button.png) + +Then select an agent mapping, for which the documentation should be shown, from the Dropdown menu. +They are alphabetically ordered, and can be filtered using the search box. + +![Picture of agent mapping dropdown](assets/config-docs-dropdown.png) + +You can also decide if you want to include the **default configuration** that is shipped with the agent by default in the documentation. +The checkbox below can be used to turn this on or off. + +The documentation for the selected agent mapping will then be shown below. +It updates whenever you change either of the settings at the top, or save changes to a configuration file in the editor. + +To help with searching documentation for specific objects, you can filter the documentation using the filter text box above. + +![Picture of documentation filtered for 'attach'](assets/config-docs-filter.png) + +Since version `2.6.2` the files, where a specific object is defined, are also tracked. +If an object is only used or mentioned in a configuration file, the file will not be shown in the particular object documentation. + +If you click on a specific file path in an object documentation, the configuration file, which defines the object will be opened. + + +## Writing your own Configuration Docs + +Part of the documentation is automatically created based on the attributes of each instrumentation object, so there will be some documentation for your own configurations without additional effort. +However, this is of course limited, so to make full use of the feature, you should extend them as described in the following. + +:::tip +See also the chapter regarding [Configuration Code Style](instrumentation/code-style.md) for an overview of recommendations on how documentation should be structured. +::: + +### Common Documentation Attributes + +With all three kinds of instrumentation objects documentation is added below the key `docs`. +Depending on the type of the instrumentation object there are more or less documentation attributes that can be set. + +For scopes and rules the following attributes are all options, for actions there a few more. + +#### Attribute: Description + +With the key `description`, you can provide a general description of what the instrumentation object is for, what it does or how it works. + +Multiline Strings within the description will be in the actual documentation with all the linebreaks, indents, etc. that you put into them. +Wrapping of lines that are too long for the documentation view will happen automatically. +Therefore, you should avoid putting linebreaks within sentences, it could lead to seemingly random linebreaks in the actual documentation view. +It is implemented that way, so you can use group the description into paragraphs or express something more specific, e.g. describe what an input of type Map should look like by writing an example as YAML into the description. + +#### Attribute: Since + +With the key `since` you can add a versioning tag as a string that will also be shown in the documentation. + +#### Example + +The documentation for a rule could then for example look like the following: + +```YAML +[...] + rules: + 'r_new_rule': + docs: + description: | + Captures execution time of current method. + The capturing will only happen if xy is true. + since: '1.42.0' + [...] +``` + +### Special Documentation Attributes for Actions + +For actions there are two more possible keys below `docs`. + +#### Attribute: Inputs + +One is `inputs` below which you can add any input names as keys and a description for them as values. + +For **special input parameters** (see [Input Parameters](instrumentation/rules.md#input-parameters) for further info) the description is **added automatically**, so you do not have to add any yourself. + +#### Attribute: Return-Value + +The other is `return-value` which should contain a description of the return value, if there is any. + +#### Example + +An action with a full documentation could look like the following: + +```YAML +[...] + actions: + 'a_attachment_get': + docs: + description: 'Reads a given attachment from a target object.' + inputs: + 'target': 'Object from which the attachment should be read.' + 'key': 'Key for attachment that should be read.' + return-value: 'The value of the wanted attachment for the given object.' + since: '1.42.0' + input: + '_attachments': 'ObjectAttachments' + 'target': 'Object' + 'key': 'String' + value: '_attachments.getAttachment(target, key)' +``` diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/overview.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/overview.md new file mode 100644 index 0000000000..699ea0ebfa --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/overview.md @@ -0,0 +1,23 @@ +--- +id: version-2.6.2-overview +title: Configuration Server Overview +sidebar_label: Overview +original_id: overview +--- + +The *inspectIT Configuration Server* is a standalone component provided by the inspectIT Ocelot project. +It can be used to centrally manage and distribute the inspectIT Ocelot agent configuration files. +For this purpose, HTTP endpoints are provided that can be queried by the agents to obtain the corresponding configuration. +This has the advantage that the manual administration of the configuration files is not required. + +![Configuration Server Architecture](assets/configuration-server-architecture.png) + +The server provides a web interface to manage all relevant settings and configurations. It can be accessed via `http://:/ui/`. By default, the configuration server is listening to port `8090`. + +In addition, a Swagger UI is provided which contains a list including documentation of the server's REST API. By default, the Swagger UI can be accessed via `http://:/swagger-ui.html`. + +## Management of Configuration Files + +Since version `1.4`, the configuration server uses Git and a local repository to manage the working directory. If a working directory already exists that was created by a configuration server in version `1.3` or lower, it is automatically migrated to a working directory managed using a local Git repository. No manual adjustments are necessary. + +Please see [Managing Files](managing-files.md) for more information on managing of the configuration files. diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/status-table-view.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/status-table-view.md new file mode 100644 index 0000000000..b281443f2b --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/status-table-view.md @@ -0,0 +1,21 @@ +--- +id: version-2.6.2-status-table-view +title: Status Table View Guide +sidebar_label: Agent Status Table View +original_id: status-table-view +--- + +The Status Table in the Agent Status page offers, in addition to displaying the most important agent information in the table, the possibility to retrieve additional information via different buttons. +Here is a short guide to help you navigate around the status table. + +![Status Table View](assets/status-table-view-ui.png) + +## Explanation of Highlighted Buttons + +| Button | Function | +|---------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ![Status Table View](assets/service-states-btn.png)
**Service States** | Displays the services (e.g. Prometheus, Jaeger, Influx, Log-Preloading, Agent Command Service, ...) and their current state (`enabled`/`disabled`).
In the future, we plan to implement the functionality to enable/disable the services in this view. | +| ![Status Table View](assets/logs-btn.png)
**Agent Logs** | Displays the logs of the service if agent commands and log preloading are enabled. | +| ![Status Table View](assets/config-btn.png)
**Current Config** | Displays the current config in `yaml` format when the agent commands are enabled. | +| ![Status Table View](assets/agent-health-icon.png)
**Agent State** | Displays the current agent state and the latest agent health incidents. | +| ![Status Table View](assets/download-archive-btn.png)
**Support Archive** | Downloads a support archive as a `.zip` file if the agent commands are enabled. The support archive contains logs (if log preloading is enabled), the current config, and environment details. | diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/configuration-sources.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/configuration-sources.md new file mode 100644 index 0000000000..d46e0f9b96 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/configuration-sources.md @@ -0,0 +1,97 @@ +--- +id: version-2.6.2-configuration-sources +title: Configuration Sources +original_id: configuration-sources +--- + +inspectIT Ocelot tries to implement the zero-configuration approach but lets you externalize the configuration and influence every bit of its configuration if this is required. +Internally it uses the Spring-based `PropertySource` order to allow overriding of configuration values. +Configuration properties are considered in inspectIT Ocelot in the following order: + +1. [Java Agent Arguments](#java-agent-arguments) +1. [Java System Properties](#java-system-properties) +1. [OS environment Variables](#os-environment-variables) +1. External Configuration Sources: + * [File-based Configuration](configuration/external-configuration-sources.md#file-based-configuration) +1. inspectIT Ocelot Defaults + +When an invalid configuration is given to inspectIT on startup, the agent will use a fallback configuration. +In this fallback configuration, the agent is inactive with the exception of listening for configuration updates. + +When giving an invalid configuration through a runtime update to the agent, the agent will simply retain the previous configuration. + +## Available Configuration Sources + +### Java Agent Arguments + +You can pass a JSON object as string to the agent via its command line arguments. +For example, to override the service name used to identify your application reporting the performance data, +you can change the `inspectit.service-name` property as follows: + +```bash +$ java -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar="{ \"inspectit\": { \"service-name\": \"My Custom Service\" }}" -jar my-java-program.jar +``` + +Note that you have to escape the quotes within your JSON string. On linux you can just use the more readable single quotes notation: + +```bash +$ java -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar='{ "inspectit": { "service-name": "My Custom Service" }}' -jar my-java-program.jar +``` + +### Java System Properties + +You can pass any configuration property as the Java System property to the Java command that you use to start your Java application. +Using this approach you can change the `inspectit.service-name` property as follows: + +```bash +$ java -Dinspectit.service-name="My Custom Service" -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar -jar my-java-program.jar +``` + +### OS Environment Variables + +Similar to the Java System properties, inspectIT Ocelot will also consider all the available operating system environment variables. +Due to the relaxed bindings, you can use upper case format, which is recommended when using system environment variables. + +```bash +$ INSPECTIT_SERVICE_NAME="My Custom Service" java -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar -jar my-java-program.jar +``` + +## Relaxed Bindings + +Note that due to the Spring-powered configuration approach, the inspectIT Ocelot agent uses Spring support for relaxed bindings. +This means that a property can be specified in different formats depending on the property source. +As suggested by Spring, the allowed formats are: + +| Property | Note | +| --- | --- | +| `inspectit.service-name` | Kebab-case, which is recommended for use in `.properties` and `.yml` files. | +| `inspectit.serviceName` | Standard camelCase syntax. | +| `inspectit.service_name` | Underscore notation (snake_case), which is an alternative format for use in `.properties` and `.yml` files. | +| `INSPECTIT_SERVICE_NAME` | UPPER_CASE format, which is recommended when using system environment variables. | + +The formats should be used in the following way, based on the type of property source: + +| Property Source | Format | +| --- | --- | +| System properties | Camel case, kebab case, or underscore notation. | +| Environment Variables | Upper case format with the underscore as the delimiter. | +| Property files (`.properties`) | Camel case, kebab case, or underscore notation. | +| YAML files (`.yaml`, `.yml`) | Camel case, kebab case, or underscore notation. | + +## Environment Information + +Each agent stores the following information about its runtime environment: + +| Property | Note | +| --- | --- | +| `inspectit.env.agent-dir` | Resolves to the path where the agent-jar is stored. | +| `inspectit.env.hostname` | The hostname where the agent is running. | +| `inspectit.env.pid` | The process id of the JVM process. | + +They are used to define the default behavior when writing the configuration persistence file and will be sent +as attributes to the configuration server when fetching the configuration. + +You can reference these properties within the configuration using e.g. `${inspectit.env.agent-dir}` +as shown in the default configuration for +[HTTP-based configuration](configuration/external-configuration-sources.md#http-based-configuration). +Referencing every other property follows the same schema. \ No newline at end of file diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/open-census-configuration.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/open-census-configuration.md new file mode 100644 index 0000000000..6f965ee040 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/open-census-configuration.md @@ -0,0 +1,35 @@ +--- +id: version-2.6.2-open-census-configuration +title: Using OpenCensus Library with inspectIT Ocelot +sidebar_label: OpenCensus Configuration +original_id: open-census-configuration +--- + +If you plan to use the OpenCensus library in an application which will be instrumented later on with inspectIT Ocelot, some special rules do apply. +Following these rules will make sure that there are no run-time problems in your application. +Furthermore, a correct configuration will make it possible to combine metrics and traces that you manually collect using the OpenCensus instrumentation library with the ones collected by the inspectIT Ocelot agent. + +1. Make sure you are using the same version of OpenCensus as inspectIT Ocelot. + + The inspectIT Ocelot agent in version 2.6.2 internally uses OpenCensus in version 0.31.1. Please adapt any OpenCensus dependency in your application to this version to avoid run-time conflicts. + ```XML + + io.opencensus + opencensus-api + 0.31.1 + + ``` + +2. Set the JVM property `inspectit.publishOpenCensusToBootstrap` to `true`. + + ``` + -Dinspectit.publishOpenCensusToBootstrap=true + ``` + + Setting the above property to `true` tells inspectIT Ocelot that you plan to use the OpenCensus library in combination with the agent. Note that this property must be specified with this exact name. The flexibility offered for all other config options does not apply here. The inspectIT Ocelot agent will make sure that all OpenCensus classes are then loaded by the bootstrap class loader. This ensures that OpenCensus implementation is shared between your manual instrumentation and the agent instrumentation, making the combination of data possible. + +3. Add the agent to the start of a JVM + + In this scenario, it is required that you add the agent via [the `javaagent` JVM argument](getting-started/installation.md#adding-the-agent-to-a-jvm). If the agent is successfully added to the JVM, it will log that the OpenCensus classes pushed to the bootstrap classloader will be used. + + It is important to state that the agent will *not* publish the OpenCensus classes to the bootstrap classloader if it is attached during runtime – even if the previously mentioned JVM argument is set! In this case, metrics and traces of *manual OpenCensus instrumentations* will *not* be collected by the inspectIT Ocelot agent. \ No newline at end of file diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/open-telemetry-configuration.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/open-telemetry-configuration.md new file mode 100644 index 0000000000..4a32c5ea2d --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/configuration/open-telemetry-configuration.md @@ -0,0 +1,37 @@ +--- +id: version-2.6.2-open-telemetry-configuration +title: Using OpenTelemetry Library with inspectIT Ocelot +sidebar_label: OpenTelemetry Configuration +original_id: open-telemetry-configuration +--- + +> TODO: finish the configuration documentation when the migration to OTEL (with the OTEL bridge) is finished, i.e., when all exporters (including OTLP exporters) are supported + +If you plan to use the OpenTelemetry library in an application which will be instrumented later on with inspectIT Ocelot, some special rules do apply. +Following these rules will make sure that there are no run-time problems in your application. +Furthermore, a correct configuration will make it possible to combine metrics and traces that you manually collect using the OpenTelemetry instrumentation library with the ones collected by the inspectIT Ocelot agent. + +1. Make sure you are using the same version of OpenTelemetry as inspectIT Ocelot. + + The inspectIT Ocelot agent in version 2.6.2 internally uses OpenTelemetry in version {opentelemetry-version}. Please adapt any OpenTelemetry dependency in your application to this version to avoid run-time conflicts. + ```XML + + io.opentelemetry + opentelemetry-api + {opentelemetry-version} + + ``` + +2. Set the JVM property `inspectit.publishOpenTelemetryToBootstrap` to `true`. + + ``` + -Dinspectit.publishOpenTelemetryToBootstrap=true + ``` + + Setting the above property to `true` tells inspectIT Ocelot that you plan to use the OpenTelemetry library in combination with the agent. Note that this property must be specified with this exact name. The flexibility offered for all other config options does not apply here. The inspectIT Ocelot agent will make sure that all OpenTelemetry classes are then loaded by the bootstrap class loader. This ensures that OpenTelemetry implementation is shared between your manual instrumentation and the agent instrumentation, making the combination of data possible. + +3. Add the agent to the start of a JVM + + In this scenario, it is required that you add the agent via [the `javaagent` JVM argument](getting-started/installation.md#adding-the-agent-to-a-jvm). If the agent is successfully added to the JVM, it will log that the OpenTelemetry classes pushed to the bootstrap classloader will be used. + + It is important to state that the agent will *not* publish the OpenTelemetry classes to the bootstrap classloader if it is attached during runtime – even if the previously mentioned JVM argument is set! In this case, metrics and traces of *manual OpenTelemetry instrumentations* will *not* be collected by the inspectIT Ocelot agent. \ No newline at end of file diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/docker-examples.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/docker-examples.md new file mode 100644 index 0000000000..c9f4805bc0 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/docker-examples.md @@ -0,0 +1,181 @@ +--- +id: version-2.6.2-docker-examples +title: inspectIT Ocelot Demo Application +sidebar_label: Demo Application +original_id: docker-examples +--- + +## inspectIT Ocelot Demo + +If you would like to see inspectIT Ocelot in action with a demo application, you can use the docker compose examples described below. +The distributed version of the [Spring PetClinic sample application](https://github.com/spring-petclinic/spring-petclinic-microservices) is used as the target application. +To demonstrate the flexibility of the OpenCensus based inspectIT agent, different demo scenarios covering different monitoring and APM components are provided. + +All the demo scenarios are fully configured with predefined dashboards, *so you can get started in 5 minutes*. + +## Launching the Demo + +:::warning +Currently, the demo is only available as Docker images for the AMD64 architecture. +On ARM platforms there may be problems with the execution. +::: + +*Pre-requisites:* To launch the demo, [Docker](https://www.docker.com/) needs to be installed on your system. +If you are using Docker Desktop or running Docker in a virtual machine, ensure that Docker has at least 4GB main memory assigned. + +Either [download](https://github.com/inspectIT/inspectit-ocelot-demo/archive/refs/heads/main.zip) or clone the [inspectIT Ocelot-Demo GitHub repository](https://github.com/inspectIT/inspectit-ocelot-demo). + +Execute the following command to launch the desired demo scenario (replace [SCENARIO_POSTFIX] with the postfix of the scenario you would like to launch): + +```bash +$ docker compose -f docker-compose-[SCENARIO_POSTFIX].yml up +``` + +This will start all the Docker containers required for the corresponding demo scenario, including the PetClinic demo application. + +You can access the demo application (PetClinic) under http://localhost:8080. +Details on accessing monitoring infrastructure components are listed below, depending on the selected demo scenario. + +### Starting the Demo on Windows Using WSL + +:::note +Using current versions of Docker Desktop and WSL 2 will work without this workaround. +::: + +If you want to execute the demo on Windows using the Windows subsystem for linux (WSL), you have to mount your hard drive to the WSL's root directory due to a problem of Docker for Windows and its volume mounting. + +For example, mounting your C drive to the root file system can be achieved using the following commands: + +```bash +sudo mkdir /c +sudo mount --bind /mnt/c /c +``` + +For more information, check out the following blog post: [Setting Up Docker for Windows and WSL to Work Flawlessly](https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly) + +If you have issues with Internet connectivity, check out the following post: [WSL2 - Fix Internet connectivity behind corporate proxy](https://gist.github.com/mandeepsmagh/f1d062fc59e4e6115385c2609b5f0448) + +## Demo Scenarios + +> In all scenarios you can use `admin` as username and `demo` as password for accessing Grafana and the inspectIT Ocelot Configuration Server. + +### Demo #1 - Prometheus, Grafana and Jaeger + +Uses Prometheus Server for metrics gathering and storage, Grafana for Dashboards. +Traces are exported to Jaeger. + +* File: `docker-compose-prometheus-jaeger.yml` +* [OpenAPM Landscape](https://openapm.io/landscape?agent=inspectit-ocelot-agent&collector=jaeger-collector,inspectit-oce-eum-server,prometheus-server&dashboarding=grafana&visualization=jaeger-query&usedges=jaeger-query:grafana&showCommercial=true&showFormats=false) + +![Demo scenario using Prometheus and Jaeger](assets/demo-landscape-prometheus-jaeger.png) + +In this scenario the following components are preconfigured and used for monitoring: +- *inspectIT Ocelot agent:* Instruments all the target demo application components. +- *inspectIT Ocelot EUM server:* Records the user's behaviour or actions while using the demo application. +- *Prometheus Server:* Gathers metrics exposed by the agent. +- *Grafana:* Provides predefined example Dashboards visualizing the metrics collected by the inspectIT Ocelot agent. +- *Jaeger:* Jaeger is used to store and query all recorded traces. + +You can access Grafana through http://localhost:3000 and the configuration server via http://localhost:8090. +The traces can be viewed in Jaeger on http://localhost:16686. +Prometheus can be accessed through http://localhost:9090. + +:::note +Currently the EUM-Server dashboards are only supported for the InfluxDB demos. You may use the `Explore` view in Grafana to view the EUM server metrics. +::: + +### Demo #2 - InfluxDB and Jaeger + +Uses InfluxDB for metrics storage and Grafana for Dashboards. +Traces are exported to Jaeger. + +* File: `docker-compose-influxdb-jaeger.yml` +* [OpenAPM Landscape](https://openapm.io/landscape?agent=inspectit-ocelot-agent&collector=jaeger-collector,inspectit-oce-eum-server&storage=influx-db&visualization=jaeger-query&dashboarding=grafana&alerting=grafana&usedges=jaeger-query:grafana&showCommercial=false&showFormats=false) +* +![Demo scenario using InfluxDB and Zipkin](assets/demo-landscape-influxdb-jaeger.png) + +In this scenario the following components are preconfigured and used for monitoring: +- *inspectIT Ocelot agent:* Instruments all the target demo application components. +- *inspectIT Ocelot EUM server:* Records the user's behaviour or actions while using the demo application. +- *InfluxDB:* Stores metric data exported by OpenCensus as time series. +- *Grafana:* Provides predefined example Dashboards visualizing the metrics collected by the inspectIT Ocelot agent. The query language [InfluxQL](https://docs.influxdata.com/influxdb/v1.8/query_language/) is used to query the data from InfluxDB. +- *Jaeger:* Jaeger is used to store and query all recorded traces. + +You can access Grafana through http://localhost:3000 and the configuration server via http://localhost:8090. +The traces can be viewed in Jaeger on http://localhost:16686. + +### Demo #3 - InfluxDB and Zipkin + +Uses InfluxDB for metrics storage and Grafana for Dashboards. +Traces are exported to Zipkin. + +* File: `docker-compose-influxdb-zipkin.yml` +* [OpenAPM Landscape](https://openapm.io/landscape?agent=inspectit-ocelot-agent&collector=zipkin-server,inspectit-oce-eum-server&storage=influx-db&visualization=zipkin-server&dashboarding=grafana&alerting=grafana&showCommercial=false&showFormats=false) + +![Demo scenario using InfluxDB and Zipkin](assets/demo-landscape-influxdb-zipkin.png) + +In this scenario the following components are preconfigured and used for monitoring: +- *inspectIT Ocelot agent:* Instruments all the target demo application components. +- *inspectIT Ocelot EUM server:* Records the user's behaviour or actions while using the demo application. +- *InfluxDB:* Stores metric data exported by OpenCensus as time series. +- *Grafana:* Provides predefined example Dashboards visualizing the metrics collected by the inspectIT Ocelot agent. The query language [InfluxQL](https://docs.influxdata.com/influxdb/v1.8/query_language/) is used to query the data from InfluxDB. +- *Zipkin:* Zipkin is used to store and query all recorded traces. + +You can access Grafana through http://localhost:3000 and the configuration server via http://localhost:8090. +The traces can be viewed in Zipkin on http://localhost:9411. + +:::note +Currently, of the EUM dashboards only the Beacons one is working for this scenario. +::: + +## Demo Grafana Dashboards +The InfluxDB and Prometheus demo scenarios include the following predefined Grafana Dashboards: + +### Agent +| Name + Grafana Marketplace | Description | Screenshot| +| -------------- | ------- | -------- | +| Service Graph [[InfluxDB]](https://grafana.com/dashboards/10142) [[Prometheus]](https://grafana.com/dashboards/10139) | Shows a graph of all instrumented and external services and their interaction. All flows are derived based on live metrics. |[![](assets/demo-dashboard-servicegraph_small.png)](assets/demo-dashboard-servicegraph.png)| +| HTTP Metrics [[InfluxDB]](https://grafana.com/dashboards/10141) [[Prometheus]](https://grafana.com/dashboards/10138) | Shows statistics of incoming and outgoing HTTP requests for each instrumented service. | [![](assets/demo-dashboard-http_small.png)](assets/demo-dashboard-http.png)| +| System Metrics [[InfluxDB]](https://grafana.com/dashboards/9601) [[Prometheus]](https://grafana.com/dashboards/9599) | Shows system metrics, such as system CPU utilization, load average and disk usage. | [![](assets/demo-dashboard-system_small.png)](assets/demo-dashboard-system.png)| +| JVM Metrics [[InfluxDB]](https://grafana.com/dashboards/9600) [[Prometheus]](https://grafana.com/dashboards/9598) | Shows JVM metrics related to JVM CPU usage, Memory (Heap and Non-Heap) and Garbage Collection. | [![](assets/demo-dashboard-jvm_small.png)](assets/demo-dashboard-jvm.png)| +| Self Monitoring [[InfluxDB]](https://grafana.com/dashboards/10143) [[Prometheus]](https://grafana.com/dashboards/10140) | Shows the instrumentation state and progress based on [self monitoring metrics](metrics/self-monitoring.md). | [![](assets/demo-dashboard-selfmonitoring_small.png)](assets/demo-dashboard-selfmonitoring.png)| + +### End User Monitoring +| Name | Description | Screenshot| +| ---------- | ------- | -------- | +| Beacons | Shows metrics for the number of processed beacons and their average processing times | [![](assets/demo-dashboard-beacons_small.png)](assets/demo-dashboard-beacons.png)| +| Trace Controller | Shows metrics for the number of processed traces, the number of spans and the average processing times for the traces| [![](assets/demo-dashboard-trace-controller_small.png)](assets/demo-dashboard-trace-controller.png)| + +## Changing Agent Configurations + +In all demo scenarios the inspectIT Ocelot agents already have their service names and used ports as well as a basic instrumentation set up. +Each scenario uses the [inspectIT Ocelot Configuration Server](../config-server/overview.md) for managing and providing the configuration files to the agents. +The web UI of the configuration server can be accessed via [localhost:8090](http://localhost:8090). + +The demo starts the following services, of which each is instrumented with an inspectIT Ocelot Agent: + +- *config-server* +- *discovery-server* +- *customers-service* +- *visits-service* +- *vets-service* +- *api-gateway* + + +## Load Test + +All demo scenarios launch with a load test written in [artillery](https://artillery.io/) that simulates user behavior. +For 10 minutes approximately every 3 seconds a new virtual user is created which either looks up a random owner from the database or edits the pet type of an existing animal. +Therefore, no real user interaction with the PetClinic is needed to generate data. + +## Further Scenarios + +For demonstrations on how to use inspectIT Ocelot with tools other than the ones in the demo scenarios described above, you can also take a look at the following blog posts: +- [Ocelot meets Bits - Enhanced Observability for Datadog](https://www.novatec-gmbh.de/en/blog/ocelot-meets-bits/) +- [Ocelot meets Lightstep - Enhanced Tracing with Lightstep](https://www.novatec-gmbh.de/en/blog/ocelot-meets-lightstep/) +- [Ocelot meets Wavefront - Enhanced Tracing with Wavefront](https://www.novatec-gmbh.de/en/blog/ocelot-meets-wavefront/) +- [Ocelot meets Elastic - Better Java Instrumentation for Elastic APM via Jaeger](https://www.novatec-gmbh.de/en/blog/ocelot-meets-elastic-better-java-instrumentation-for-elastic-apm-via-jaeger/) + +:::note +If you have any examples of your own, additions to this list are happily welcome! +::: diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/installation.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/installation.md new file mode 100644 index 0000000000..3200fccd04 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/installation.md @@ -0,0 +1,159 @@ +--- +id: version-2.6.2-installation +title: Installation +original_id: installation +--- + +This section describes the installation details for the inspectIT Ocelot agent. + +## Supported Java Runtime Environments + +The inspectIT Ocelot supports Java Runtime Environments in version 1.8.0 and above. You will not be able to use the agent with the lower Java versions. +The agent works with different JRE distributions including Oracle, openJDK, Azul, etc. + +It is recommended to always use the latest minor release of your current Java Runtime Environment version in order to ensure straightforward operation. + +## Adding the Agent to a JVM + +The best option for using the inspectIT Ocelot is to include it to the start of the JVM by using the `-javaagent` command-line option. +This way the agent will be initialized before your application starts. + +```bash +$ java -javaagent:"/path/to/inspectit-ocelot-agent-2.6.2.jar" -jar my-java-program.jar +``` + +> Some application servers have dedicated scripts that are used to launch the actual JVM that runs the application. In such cases, you must alter the start-up scripts in order to instrument the correct JVM. + +## Attaching the Agent to a Running JVM + +inspectIT Ocelot also supports attaching the agent to an already running JVM. +In such a scenario the collection of metrics and traces will start from the point of the attachment. + +The attaching can easily be done using the agent itself and executing the following command: + +```bash +$ java -jar inspectit-ocelot-agent-2.6.2.jar [] +``` + +In the following example, we are attaching the agent to the JVM process `1337` and passing some [additional arguments](configuration/configuration-sources.md#java-agent-arguments) to it: +```bash +$ java -jar inspectit-ocelot-agent-2.6.2.jar 1337 '{"inspectit":{"service-name":"my-agent"}}' +``` + +> The agent is internally using the utility [jattach](https://github.com/apangin/jattach) for attaching itself to a running JVM. + +In order to find the process ID of a running JVM, you can use the `jcmd` to list all the running Java processes on your machine: + +```bash +$ jcmd -l +``` + +### Attaching Using jattach + +Another way of attaching the agent to a running JVM is to use the utility [jattach](https://github.com/apangin/jattach): + +```bash +$ ./jattach.sh load instrument false /path/to/inspectit-ocelot-agent-2.6.2.jar='{"inspectit.service-name" : "MyService"}' +``` +In this example we're also passing [JSON arguments](configuration/configuration-sources.md#java-agent-arguments) to the agent in order to configure its service name. + +> Using the attach options has some limitations with respect to using the OpenCensus instrumentation library in combination with the inspectIT Ocelot agent. Please refer to [OpenCensus Configuration](configuration/open-census-configuration.md) section to understand these limitations. + +## Using the Agent With a Security Manager + +If a Java Security Manager is enabled, the agent needs to be granted additional permissions to work. +For this, add the following to your policy file: + +``` +grant codeBase "file:" { + permission java.security.AllPermission; +}; +``` + +The correct policy file location depends on different factors. +See the [official Java documentation](https://docs.oracle.com/en/java/javase/17/security/permissions-jdk1.html#GUID-789089CA-8557-4017-B8B0-6899AD3BA18D) for further information. + +## Using the Agent with Kubernetes + +There are several ways to use the agent in a Kubernetes cluster. +For example, you could integrate the agent directly into the application container images, but this requires customizing all images. + +Another possibility is that the agent is automatically injected into the application containers using an **operator** and attached to the JVM processes. +For this purpose, the [OpenTelemetry K8s Operator](https://github.com/open-telemetry/opentelemetry-operator) can be used, with which it is possible to automatically roll out the inspectIT Ocelot Java Agent. +It is still under development, so it is not feature-complete, but depending on your needs the current version could already provide everything needed. + +:::warning Up-to-dateness of the Documentation +Since the OpenTelemetry K8s operator is currently under heavy development, the installation steps described below **may be outdated**. +They may nevertheless be helpful in navigating the OpenTelemetry Operator installation documentation by showing you which parts you need. +::: + +### Installing the Operator + +Install the OpenTelemetry Operator as described in its [official readme file](https://github.com/open-telemetry/opentelemetry-operator#getting-started). This includes the following steps: + +1. Install the [cert-manager](https://cert-manager.io/docs/installation/) in your cluster if you have not done it already. +2. Install the operator using the following command. Please note that this will install the latest version of it: + + ```shell + kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml + ``` + + By adjusting the URL to a different GitHub release, a specific version of the operator can be used: + + ```shell + kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v{version}/opentelemetry-operator.yaml + ``` + +### Using the Operator + +1. Create an `Instrumentation` object as shown below. Set the `spec.java.image` to the inspectIT Ocelot agent container image you would like to use: + + :::note + Please note that only container images of the inspectIT Ocelot Agent starting from version `1.15.2` are compatible and work with the OpenTelemetry K8s Operator. + ::: + + ```yaml + apiVersion: opentelemetry.io/v1alpha1 + kind: Instrumentation + metadata: + name: my-instrumentation + spec: + java: + image: inspectit/inspectit-ocelot-agent:1.15.2 + ``` + +2. Annotate namespaces or containers that should receive the agent as described in the [official readme file](https://github.com/open-telemetry/opentelemetry-operator#getting-started). The possible values for the annotation can be: + + - `true` - inject the `Instrumentation` resource from the namespace. + - `my-instrumentation` - name of Instrumentation CR instance. + - `false` - do not inject + + The following annotation can be used for this: + ```yaml + instrumentation.opentelemetry.io/inject-java: "true" + ``` + + :::warning Ensure Correct Referencing + If the operator cannot find the instrumentation object, e.g. because none was created or the name was written incorrectly in the annotation, the containers will not be started! + ::: + +3. (Optional) Add environment variables to the containers to configure the agent. See the following section for using [environment variables to configure](configuration/configuration-sources.md#os-environment-variables) the inspectIT Ocelot agent. + + For example, to set a service-name for the agent and connect it to a specific configuration-server, you could set the `INSPECTIT_CONFIG_HTTP_URL` and `INSPECTIT_SERVICE_NAME` environment variable like in the following: + + ```yaml + containers: + - image: my-app-image + name: my-app + env: + - name: INSPECTIT_CONFIG_HTTP_URL + value: http://my-ocelot-config-server:8090/api/v1/agent/configuration + - name: INSPECTIT_SERVICE_NAME + value: my-service-name + ``` + + You can also take a look at the [deployment file](https://github.com/inspectIT/trading-demo-application/blob/main/k8s/deployment.yaml) of the [trading demo application](https://github.com/inspectIT/trading-demo-application) where exactly this is set up. + +4. Start or restart the containers to trigger the injection and attachment of the agent. + + Currently, the operator **will not automatically restart running containers** in case changes are made to the `Instrumentation` objects. However, there are plans to provide the ability to restart containers in order to roll out changes of the configurable `Instrumentation` objects automatically (see [issue #553](https://github.com/open-telemetry/opentelemetry-operator/issues/553)). diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/quick-start.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/quick-start.md new file mode 100644 index 0000000000..838655f3fa --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/getting-started/quick-start.md @@ -0,0 +1,22 @@ +--- +id: version-2.6.2-quick-start +title: Quick Start +original_id: quick-start +--- + +You can find and download all released versions of inspectIT Ocelot in our [GitHub](https://github.com/inspectIT/inspectit-ocelot/releases) repository. +You can get the current version on the following link: + +```bash +$ wget https://github.com/inspectIT/inspectit-oce/releases/download/2.6.2/inspectit-ocelot-agent-2.6.2.jar +``` + +The best way to start using inspectIT Ocelot is to attach the Java agent when starting your Java program. +Use the `-javaagent` command-line option to reference the inspectIT Ocelot jar: + +```bash +$ java -javaagent:"/path/to/inspectit-ocelot-agent-2.6.2.jar" -jar my-java-program.jar +``` + +The [Installation](installation.md) section further describes what options are available for installing the agent, as well as how you can attach the agent to an already started JVM. +In the [Configuration](configuration/configuration-sources.md) section you can find more details on how to configure the inspectIT Ocelot agent. \ No newline at end of file diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/instrumentation/process.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/instrumentation/process.md new file mode 100644 index 0000000000..58df70eba8 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/instrumentation/process.md @@ -0,0 +1,97 @@ +--- +id: version-2.6.2-process +title: Instrumentation Process +original_id: process +--- + +The approach inspectIT Ocelot takes for instrumenting is fundamentally different from the approach of most other JVM instrumentation agents. +InspectIT Ocelot does *not* instrument classes when they are loaded, the instrumentation is performed purely asynchronous in the background. + +In this background task inspectIT Ocelot essentially looks at every loaded class and performs an instrumentation if required by the active configuration. Hereby, the agent manages the classes he has to analyze in a queue. This queue is processed in batches to ensure that no CPU resources are blocked if they are required by the instrumented application. The batching is configurable using the `internal` settings: + +```yaml +inspectit: + instrumentation: + # settings for fine-tuning the instrumentation process + internal: + # the time to pause between executing batches of class instrumentation updates + inter-batch-delay: 50ms + # defines how many classes are checked at once for updates of their configuration per batch + class-configuration-check-batch-size: 1000 + # defines the maximum number of classes which are instrumented per batch + class-retransform-batch-size: 10 + + # defines how often the agent should check if new classes have been defined. + new-class-discovery-interval: 10s + # defines how often the new class discovery is performed after a new class has been loaded + num-class-discovery-trials: 2 + + # defines whether orphan action classes are recycled or new classes should be injected instead + recyclingOldActionClasses: true +``` + +In addition, the size of the instrumentation queue can be used as an indicator for the instrumentation progress. +It is accessible via the [self-monitoring](metrics/self-monitoring.md) of the agent. + +InspectIT allows you to perform instrumentation by injecting custom code into your application. +If your JVM has a `SecurityManager` enabled, you might also want to control the `ProtectionDomain` of these injected classes. + +By default, inspectIT will use its own `ProtectionDomain` for injected classes. +Alternatively, you can make inspectIT to use the `ProtectionDomain` for which the action is being created using the following configuration: + +```yaml +inspectit: + instrumentation: + internal: + use-inspectit-protection-domain: false +``` + +## Synchronous instrumentation (BETA!) +:::caution +Enabling synchronous instrumentation in Java 8 environments will result in significant boot time performance degradation! +See See: JDK-7018422 +::: + +By default, all instrumentation is performed purely asynchronously in the background. There may be situations where this is not appropriate and a class must be instrumented directly at the first load, +e.g. in batch processes. + +InspectIT can be configured to instrumented classes on first class load by updating the following configuration: +```yaml +inspectit: + instrumentation: + internal: + async: false +``` + +## Delayed instrumentation +Despite instrumenting asynchronously or synchronously, inspectIT always starts the instrumentation process as soon as +the agent is attached to a JVM. There are cases in which it is desirable to postpone the start of the instrumentation +process. Although this is rarely necessary inspectIT provides the possibility to do so via system property +`inspectit.start.delay` or OS environment variable `INSPECTIT_START_DELAY`. + +You provide a value interpreted as milliseconds the agent shall wait before the instrumentation process starts. If you +do not provide a value the instrumentation process will start immediately. + +The Agent expects positive integers excluding zero. For all other values the agent will print an error message on stderr +and continue as if there was no value supplied. + +If you specify both system property and OS environment variable, the system property will take precedence. + +Since this option has an impact before the agent fetches any configuration from the +[Configuration Server](config-server/overview.md) you cannot specify that value like any other inspectIT configuration +property. It is only available as system property or OS environment variable. + +Example using system property: +```bash +# this will delay the instrumentation process by 10 minutes +$ java -javaagent:"/path/to/inspectit-ocelot-agent-2.6.2.jar" \ + -Dinspectit.start.delay=600000 \ + -jar my-java-program.jar +``` + +Example using OS environment variable (using bash): +```bash +# this will delay the instrumentation process by 5 minutes +$ export INSPECTIT_START_DELAY=300000 +$ java -javaagent:"/path/to/inspectit-ocelot-agent-2.6.2.jar" -jar my-java-program.jar +``` diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/metrics/tag-guard.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/metrics/tag-guard.md new file mode 100644 index 0000000000..7b7c97f936 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/metrics/tag-guard.md @@ -0,0 +1,99 @@ +--- +id: version-2.6.2-tag-guard +title: Tag-Guard +original_id: tag-guard +--- + +Since version `2.6.0` it is possible to limit the amount of tag values of metrics. +This can be useful for controlling the amount of tag values, which will be written to your time series database +(e.g. InfluxDB or Prometheus). A high amount of unique tag values for a metric will result in a high cardinality, +which in turn might lead to performance or memory issues in your time series database. + +The recorded tag values for each measure of an agent will be stored inside a local JSON file. This file serves +as the tag-guard-database and helps to check, if tag values exceeded their limit. + +### Configuring Tag-Guard + +You can set the Tag-Guard configuration in `inspectit.metrics.tag-guard`. + +| Property | Default | Description | +|----------------------------------|--------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| `.enabled` | `true` | Only when the tag-guard is enabled, the tag value limits will be checked. +| `.database-file` | `${inspectit.env.agent-dir}/${inspectit.service-name}/tag-guard-database.json` | The location of the JSON file with all recorded tag values. | +| `.schedule-delay` | `30s` | The delay for the scheduler, which will regularly compare the tag-guard-database with the configured tag value limits. | +| `.overflow-replacement` | `TAG_LIMIT_EXCEEDED` | After exceeding it's configured tag value limit, every tag will use this overflow replacement as value. | +| `.max-values-per-tag` | `1000` | The global tag value limit for every measure. | +| `.max-values-per-tag-by-measure` | `{}` | A map with measure names as key and their specific tag value limit as value. | + +There are three ways to define a tag value limit for measures. They are prioritized in the following order: + +1. Inside a metric definition for a particular measure +2. Globally for specific measures via `may-values-per-tag-by-measure` +3. Globally for all measures via `max-values-per-tag` + +This means that a tag value limit inside a metric definition will overwrite all other tag value limits +for the particular metric. A configured tag value limit in `max-values-per-tag-by-measure` will only overwrite the +globally set tag value limit in `max-values-per-tag` for the particular measure, but not a configured tag value limit +inside the metric definition. Let's look at an example: + +```yaml +inspectit: + metrics: + tag-guard: + max-values-per-tag: 1000 + max-values-per-tag-by-measure: + my_metric: 200 +``` + +In this configuration the global tag value limit is set to 1000, which means that every measure can only record 1000 unique +tag values for each tag. However, this does not apply to the measure `my_metric`, because the global tag value limit is +overwritten by `max-values-per-tag-by-measure` with 200. Thus, the measure `my_metric` can only record a maximum of 200 unique +tag values for each tag. + +Now, let's add another configuration: + +```yaml +inspectit: + metrics: + definitions: + 'my_metric': + tag-guard: 100 +``` + +This metric definition will overwrite the tag value limit specified in `max-values-per-tag-by-measure` for the measure `my_metric`, +resulting in a tag value limit of 100. Every other measure still uses the globally configured tag value +limit of 1000. + + +### Agent Health Monitoring + +If the tag value for a specific agent is exceeded, the Tag-Guard scheduler will detect an overflow and change +the agent health to `ERROR`. +Additionally, an agent health incident will be created, mentioning which tag-key has exceeded its tag value limit. +In the [Agent Status Table View](../config-server/status-table-view.md) of the Configuration-Server you can click on the +health state icon of a particular agent to view its last agent health incidents. You can set the amount of buffered incidents +with `inspectit.self-monitoring.agent-health.incident-buffer-size`. A list of incidents could look like this: + +![List of agent health incidents](assets/agent-health-incidents.png) + + +### How To Fix A Tag Value Overflow + +If a tag value limit was exceeded, there are two options to resolve the agent health `ERROR`. + +The **first option** would be to increase the tag value limit. Probably the limit has been estimated too low and thus has +to be increased. After increasing the tag value limit, the tag-guard-database scheduler will resolve the `ERROR`. + +The **second option** would be to adjust your configuration or application so the tag value limit should not be exceeded anymore. +After the adjustment, you will have to "reset" the recorded tag values in the tag-guard-database to resolve the `ERROR`. +One way to reset the tag-guard-database is to delete the local JSON file. However, this will delete all recorded tag values +and might not be the preferred solution.
+A more preferable solution would be to only reset the tag values for a specific tag of a measure, +which has exceeded its tag value limit. +To do this, you could use the _**jq command-line JSON processor**_, which has to be installed on your system manually. +For example, you could use the following command, if you would like to delete all recorded tag values for the tag _my_tag_ inside the measure _my_metric_: + +- Unix: `jq '.my_metric.my_tag = []' tag-guard-database.json > temp.json && mv temp.json tag-guard-database.json` +- Windows: `jq ".my_metric.my_tag = []" tag-guard-database.json > temp.json && move temp.json tag-guard-database.json` + +In future versions of inspectIT there might be an option to reset specific tag values directly in the Configuration-Server UI. diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/tracing/tracing.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/tracing/tracing.md new file mode 100644 index 0000000000..4ba149fdbf --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/tracing/tracing.md @@ -0,0 +1,159 @@ +--- +id: version-2.6.2-tracing +title: Tracing +original_id: tracing +--- + +This section provides all the information on trace collection with inspectIT Ocelot. + +The inspectIT Ocelot configuration has a master switch for tracing, which can be used to completely disable anything that has to do with trace collection and exporting. +Tracing in the agent can be completely disabled by setting the `inspectit.tracing.enabled` property to `false`. +This way any default inspectIT setting or anything else defined for trace collection will be overruled. +If used, the switch makes sure that the inspectIT Ocelot agent: + +* disables all trace exporters +* removes tracing from all [instrumentation rules](instrumentation/rules.md) + + +### Global Sampling Rate + +It is possible to globally regulate the number of traces generated through [sampling](https://opencensus.io/tracing/sampling/). +You can configure the probability with which a trace ends up being collected via `inspectit.tracing.sampleProbability`. +E.g. setting the value to `0.1` will record only 10% of all traces. + +The global sampling is also influenced by the `sample-mode` that can be set in `inspectit.tracing.sampleMode`, see the table below. +By default, `PARENT_BASED` is used. + +| Sample mode | Description | +|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `PARENT_BASED` (default for `inspectit.tracing.sample-mode`) | The setting of the `sample-probability` only has an effect if **no sampling decision** has been made yet. If a parent span has already decided that a trace is sampled or not sampled, this decision will continue to be used. This means that, for example, a method within a trace that has already been started will always be recorded, even if the sample setting has been set to `0`. This also applies to the opposite case where a span has decided not to sample and the sampling rate has been set to `1`. In this case the method will **not** be recorded!. See also the [official documentation of OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#parentbased). | +| `TRACE_ID_RATIO_BASED` | The sampling decision is made for each span, regardless of the parent span's sampling decision, see also the [official documentation of OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#parentbased). | +| `HYBRID_PARENT_TRACE_ID_RATIO_BASED` (default for `inspectit.instrumentation.rules.[name-of-rule].tracing.sample-mode`) | The span is sampled if the parent span has been sampled, otherwise applies a [TraceIdRatioBasedSampler](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampler). This behavior is similar to the previously used [ProbabilitySampler](https://github.com/census-instrumentation/opencensus-java/blob/master/api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java) from OpenCensus. | + + +By default, the sample probability is `1.0`, meaning 100% (each trace is recorded). + +:::tip +This global setting only acts as a default value and can be **overridden** by [individual rules](instrumentation/rules.md#trace-sampling). +For example, with this technique it can be achieved that a method (e.g. HTTP entrypoint) uses different sampling rates depending on the parameters (e.g. current HTTP path). +::: + +### Additional Properties + +You can additionally define the following global properties (`inspectit.tracing`-property) + +|Property|Default| Description | +|---|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`sample-mode`|`PARENT_BASED`| The root sample mode to be used for sampling, see above. Supported modes are [`PARENT_BASED`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#parentbased), [`TRACE_ID_RATIO_BASED`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#parentbased) and `HYBRID_PARENT_TRACE_ID_RATIO_BASED` (similar to [OpenCensus ProbabilitySampler](https://github.com/census-instrumentation/opencensus-java/blob/master/api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java)). For more information visit the [official documentation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampler). | +|`max-export-batch-size`|512| The max export batch size for every export, i.e., the maximum number of spans exported by the used `BatchSpanProcessor` | +|`schedule-delay-millis`|5000| The delay interval between two consecutive exports in milliseconds. + +:::warning +These properties take only effect once when the agent is starting. If you change these properties while the agent is running, they will not take effect until the agent restarted. +::: +### Common Tags as Attributes + +Globally defined [common tags](metrics/common-tags.md) used when recording metrics can also be inserted as attributes in traces. +The property `inspectit.tracing.add-common-tags` defines the behavior of this feature. +Available options are: + +* `NEVER` - Never add common tags as attributes to spans. +* `ON_GLOBAL_ROOT` - Add common tags only to a global span root. Thus, only to the first span of each trace. +* `ON_LOCAL_ROOT` (default) - Add common tags to local span roots. If a trace spans over several JVMs, then attributes will be set on the first span of each JVM. +* `ALWAYS` - Add common tags as attributes to all spans. + +### Trace Correlation and Distributed Tracing + +The inspectIT Ocelot agent supports out-of-the-box distributed tracing, which allows traces to be correlated across multiple components to trace the entire flow through a system. +By default, the agent supports correlating a communication via HTTP and JMS. +To achieve this, correlation information is exchanged during the communication (for example by injecting additional headers into requests), for which the **B3 Propagation format is used by default**. + +If you want to use the agent together with other components that also perform distributed tracing but do not support the correlation information in B3 format, this can be adjusted with the following configuration: + +```YAML +inspectit: + tracing: + propagation-format: B3 # the format for propagating correlation headers +``` + +Currently, the following formats are supported for sending correlation information: + +| Property | Format | Description +|---|---|---| +|`B3` *(default)*|[B3 Propagation](https://github.com/openzipkin/b3-propagation/blob/master/README.md)|B3 Propagation used by, e.g. Zipkin. +|`TRACE_CONTEXT`|[W3C Trace Context](https://www.w3.org/TR/trace-context/#traceparent-header)|Standard headers and a value format to propagate context information. +|`DATADOG`|[Datadog Format](https://github.com/inspectIT/inspectit-ocelot/issues/792)|Headers used by Datadog for context correlation. + +:::important +It is important to note that this configuration refers to the format of the correlation information used to **send this data**. When processing correlation information that the agent receives, it automatically uses the correct format. +::: + +### Adding Metric Tags + +It is possible to include all metrics tags of the current rule scope as tracing attributes. +This way it isn't necessary to define key-value pairs twice for metrics as well as tracing. +However, it is only possible to use metric tags as tracing attributes, but not vice versa! + +You can disable this feature in the tracing configuration: + +```YAML +inspectit: + tracing: + add-metric-tags: true +``` + +In this example, both tags of the metric `my_counter` will be used as attributes for the tracing within this rule. + +```YAML +rules: + 'r_example': + include: + 'r_myRule': true + entry: + 'my_data': + action: 'a_getData' + metrics: + my_counter: + value: 1 + data-tags: + 'example': 'my_data' + constant-tags: + 'scope': 'EXAMPLE' +``` + +Each tag key can only be used once within one trace. Thus, if a tag key has been assigned multiple values within one rule, +the acquired tag value will be determined hierarchically. Tag keys defined in `metrics.data-tags` will overwrite tag keys +defined in `metrics.constant-tags`. Tag keys defined in `tracing.attributes` will always overwrite tag keys defined in `metrics`. +In the example below, the tracing attributes will use 'trace' as value for 'myTag' and 'yourData' as value for 'yourTag'. + + +```YAML +rules: + 'r_example': + tracing: + attributes: + 'myTag': 'trace' + metrics: + my_counter: + data-tags: + 'myTag': 'myData' + 'yourTag': 'yourData' + constant-tags: + 'yourTag': 'CONSTANT' +``` + + +### Using 64-Bit Trace IDs + +Since version 2.0.0, the inspectIT Ocelot Agent is able to generate trace IDs with a size of 64 bits instead of the 128 bit trace IDs used by default by the agent. +The functionality that trace IDs with a length of 64 bits are generated can be activated with the following configuration: + +```YAML +inspectit: + tracing: + use-64-bit-trace-ids: true +``` + +:::important +Please note that some propagation formats do not support 64-bit Ids, such as the W3C "Trace Context". In this case the 64-bit trace IDs are padded with leading zeros. +::: diff --git a/inspectit-ocelot-documentation/website/versions.json b/inspectit-ocelot-documentation/website/versions.json index 4b57f8043e..c7bfd343ab 100644 --- a/inspectit-ocelot-documentation/website/versions.json +++ b/inspectit-ocelot-documentation/website/versions.json @@ -1,4 +1,5 @@ [ + "2.6.2", "2.6.1", "2.6.0", "2.5.6",