From 7991402519d01a465ffa2f5020a1be58420ab69d Mon Sep 17 00:00:00 2001 From: NTTechnicalUser Date: Wed, 13 Dec 2023 11:07:35 +0000 Subject: [PATCH] Publish documentation for release 2.6.0 --- .../config-server/agent-mappings.md | 96 ++++++++++ .../config-server/files-staging.md | 174 ++++++++++++++++++ .../config-server/managing-files.md | 98 ++++++++++ .../configuration/configuration-sources.md | 97 ++++++++++ .../open-census-configuration.md | 35 ++++ .../open-telemetry-configuration.md | 37 ++++ .../getting-started/installation.md | 159 ++++++++++++++++ .../getting-started/quick-start.md | 22 +++ .../version-2.6.0/instrumentation/process.md | 97 ++++++++++ .../version-2.6.0/metrics/tag-guard.md | 99 ++++++++++ .../version-2.6.0/tracing/tracing.md | 159 ++++++++++++++++ .../version-2.6.0-sidebars.json | 68 +++++++ .../website/versions.json | 1 + 13 files changed, 1142 insertions(+) create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/agent-mappings.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/files-staging.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/managing-files.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/configuration-sources.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/open-census-configuration.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/open-telemetry-configuration.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/getting-started/installation.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/getting-started/quick-start.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/instrumentation/process.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/metrics/tag-guard.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/tracing/tracing.md create mode 100644 inspectit-ocelot-documentation/website/versioned_sidebars/version-2.6.0-sidebars.json diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/agent-mappings.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/agent-mappings.md new file mode 100644 index 0000000000..21245f6d06 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/agent-mappings.md @@ -0,0 +1,96 @@ +--- +id: version-2.6.0-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.5.7` 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.0/config-server/files-staging.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/files-staging.md new file mode 100644 index 0000000000..20e861cc8b --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/files-staging.md @@ -0,0 +1,174 @@ +--- +id: version-2.6.0-files-staging +title: File Staging Using Remote Git +sidebar_label: File Staging +original_id: files-staging +--- + +:::tip +It is recommended to first familiarize yourself with [how the configuration server manages files](config-server/managing-files.md) before reading this chapter. +::: + +Since version `1.11.0` the Configuration Server offers the possibility that external Git repositories can be connected. +This allows configuration files to be obtained from an external Git repository and also transferred to it. +This allows us to secure configuration files and agent mappings (e.g. for creating backups), initialize configuration servers with a specific set of configuration files or chain several configuration servers together. +The latter can be used, for example, to cover more complex scenarios, such as synchronizing configuration files across multiple system stages. + +:::important +All configuration server properties mentioned below refer to being set under the `inspectit-config-server.remote-configurations` key! +::: + +Note that this feature is **disabled by default**. +It can be enabled by setting the property `inspectit-config-server.remote-configurations.enabled` to `true`. + +## Synchronization Workflow + +The synchronization of configuration files can be divided into two areas: pulling and pushing configuration files. +These two options can be used together or separately. +For example, a configuration server can be set to only pull files from a remote Git repository, but not push any away. + +Using the following diagram, the process and the individual steps will be explained in more detail. + +![Configuration Files Staging Workflow](assets/staging-workflow.png) + +### Pulling Configuration Files + +The configuration server can be set to pull configuration files from a specific branch from a remote Git. +Depending on the configuration, this can be done when the **server is started** (disabled by default) or [**triggered by a webhook**](#triggering-file-pulling-using-webhooks). + +In order for this to work, a remote Git repository must be configured and the appropriate branch specified. +This can be configured using the `pull-repository` property. +Please refer to the [Repository Configuration section](#repository-configuration) for more information on how to configure a repository and its branch. + +![Configuration Files Staging Workflow](assets/staging-pull.png) + +When the synchronization process *(1)* is triggered, the configuration server obtains all files that have changed (added, modified, deleted) since the last synchronization and puts them into the local `WORKSPACE` Branch. +Please note that the **synchronized files overwrite the local files**! +Changes that were only made locally will be overwritten and lost. +Files that have been created or changed locally, but were **not included in the changes** made on the remote branch, remain unaffected. + +By default, the configuration server will not synchronize on startup. However, this can be set with the `pull-at-startup` option. + +#### Initial Synchronization + +:::warning +Note that this setting may lead to **overwriting existing configurations**. You should only activate this option if you know what you are doing. +::: + +When the configuration server performs a synchronization for the **very first time** (for example, because the server has been upgraded and this feature is now available), **no files are pulled** by default. +Only changes that happen from now on will also be synchronized. +This is done so that configuration files are not accidentally overwritten and lost. + +This behavior can be changed with the option `initial-configuration-sync`. +If this option is set to `true`, the configuration server pulls all files that are in the remote Git repository at the very first time. +Please note that only files are added or overwritten. +No files are deleted! + +This option is useful if, for example, a new instance of a configuration server should be populated with a set of configuration files. + +### Auto-Promotion of Configuration Files + +When the configuration server pulls configuration files, they will be put into the `WORKSPACE` branch. +By default, the server **automatically performs a promotion** of the pulled files after a successful pull, so that the `WORKSPACE` and the `LIVE` branch are up-to-date. +However, this function can be disabled with the `auto-promotion` property. +If this option is disabled, the server will not perform an automatic promotion and the `LIVE` branch will remain untouched. + +### Pushing Configuration Files + +The configuration server can be configured to send the `LIVE` branch respectively files that are promoted to it to a remote Git repository. +Depending on the configuration, this can be done when the **server is started** (disabled by default) or when a **configuration file promotion** is done. + +In order for this to work, a remote Git repository must be configured and the appropriate branch specified. +This can be configured using the `push-repository` property. +Please refer to the [Repository Configuration section](#repository-configuration) for more information on how to configure a repository and its branch. + +![Configuration Files Staging Workflow](assets/staging-push.png) + +If pushing of the configuration files is triggered *(2)*, the configuration server pushes the files to the configured remote Git repository. +It is important to note that the sending is **forced by default**, but this can be disabled with the `push-repository.use-force-push` option. +Even if this option is enabled, the server will always try an unforced push first. +Since this can cause a commit to be lost in the remote repository due to the forced push, it is recommended that only a single configuration server can push to the target branch. + +:::warning +Note that by default, pushing the branch is **forced**, which could inadvertently overwrite data. +::: + +This process can also be triggered by an automatic promotion due to pulling configuration files from a remote Git repository. + +:::note +When the configuration server initialized its Git repository for the first time, the `LIVE` branch continues the commit history of the specified branch of the push repository. +As a result, new commits can be pushed unforced, as long as the push repository has no external changes. +**Only the commit history is adopted**, while the file content remains as before the Git initialization. +::: + +## Triggering File Pulling Using Webhooks + +As already mentioned, pulling configuration files from a remote Git repository can be done at startup of the configuration server, or can be triggered by a webhook. +Triggering this process through a webhook can be handy if you want to trigger a synchronization whenever a change happens on the configured remote branch, for example. + +For this purpose, the configuration server provides the following endpoint, which can be triggered via an HTTP GET request: `/api/v1/hook/synchronize-workspace`. + +:::note +This endpoint will only work if pulling configuration files from a remote Git repository has been enabled and configured. +::: + +For security reasons, this endpoint can only be accessed with a predefined token, so that not any arbitrary user can trigger this process. +This token is included in the request via the query parameter `token`. + +The tokens can be set up using the following property: `inspectit-config-server.security.webhook-tokens`. +It is possible to define several tokens, which can be used if individual tokens have to be deactivated again. + +```yaml +inspectit-config-server: + security: + webhook-tokens: + - 'very_secure_token' + - 'another_very_secure_token' +``` + +#### Example + +Assuming the configuration server is started locally on the default port `8090` and a token `very_secure_token` has been set up for webhook access, this can be triggered with the following CURL command. + +```bash +$ curl http://localhost:8090/api/v1/hook/synchronize-workspace?token=very_secure_token +``` + +## Chaining Multiple Configuration Servers + +Using the feature that remote Git repositories can be connected to pull and push configuration files, it is now also possible to link multiple configuration servers together. +This can be used, if several configuration servers are in use, which receive the respective configuration files of the previous server. +This is very useful, if e.g. several system stages exist, which used separate configuration servers. + +![Configuration Server Chaining using remote Git repository](assets/staging-chain.png) + +In order to do this, the configured push and pull branch can be set to the same remote Git repository respectively branch. + +## Available Configuration Properties + +:::important +All configuration server properties mentioned below refer to being set under the **`inspectit-config-server.remote-configurations`** key! +::: + +| Property | Default | Note | +| --- | --- | --- | +| `enabled` | `false` | Whether this feature is enabled and remote Git repositories should be used for configuration management. | +| `push-at-startup` | `false` | Whether the current live branch should be pushed during startup. | +| `pull-at-startup` | `false` | Whether the remote source branch should be fetched and merged into the current workspace branch during startup. | +| `initial-configuration-sync` | `false` | Defines whether the configuration files of the configuration source repository should be pulled on the initial configuration synchronization. The initial synchronization is not related to the `pull-at-startup` property!
[Read the documentation](#initial-synchronization) for detailed information on this property! | +| `auto-promotion` | `true` | Whether synchronized files should be promoted automatically, after they have been fetched from the configuration remote. | +| `pull-repository` | `null` | The remote Git repository which will be used to fetch workspace-configurations from.
See [Repository Configuration](#repository-configuration). | +| `push-repository` | `null` | The remote Git repository which will be used to push live-configurations to.
See [Repository Configuration](#repository-configuration). | + +### Repository Configuration + +| Property | Default | Note | +| --- | --- | --- | +| `remote-name` | `[pull/push]-remote-configuration` | The name of the remote ref in the local Git repository. | +| `git-repository-uri` | `null` | The URI to the remote Git repository. Examples: `https://github.com/user/repo.git`, `git@github.com:user/repo.git` | +| `branch-name` | `remote-[workspace/live]` | The branch name on the remote Git repository. | +| `use-force-push` | `true` | Whether force push should used for pushing to this remote. This is only available for the `push-repository` property. | +| `authentication-type` | `NONE` | The type of authentication to use. Possible values: `NONE`, `PASSWORD`, `PPK`. | +| `username` | `null` | The username for accessing the remote repository. Only used in case of `PASSWORD` authentication. | +| `password` | `null` | The password for accessing the remote repository. Only used in case of `PASSWORD` authentication. | +| `private-key-file` | `null` | Additional private key to use for SSH authentication. The server will automatically load the known hosts and private keys from the default locations (identity, id_rsa and id_dsa) in the user’s `.ssh` directory. Only used in case of `PPK` authentication. | diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/managing-files.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/managing-files.md new file mode 100644 index 0000000000..4c568015be --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/config-server/managing-files.md @@ -0,0 +1,98 @@ +--- +id: version-2.6.0-managing-files +title: Managing Files +sidebar_label: Managing Files +original_id: managing-files +--- + +The configuration server internally uses Git to manage its working directory. +This allows a versioning of configurations as well as the agent mappings, so that it is possible to track when and how a file was created, +changed or deleted. Additionally, it allows unwanted changes to be reverted and configuration files to be restored that +would otherwise be lost. + +Furthermore, a staging of configurations and agent mappings is possible. By default, the configuration server has two +branches (`WORKSPACE` and `LIVE`) which can be used as the basis for the configurations to be delivered. +All changes made by users to the configuration files and the agent mappings affect the `WORKSPACE` branch. +The `LIVE` branch cannot be changed directly by users. A change to the `LIVE` branch is only possible by transferring +an already done change to the `WORKSPACE` branch to the `LIVE` branch - in this case called "promotion". + +:::tip +It is possible for agents to obtain the configurations exclusively from the `LIVE` branch. As a result, users can now +edit configuration files without having to deliver these - possibly incomplete changes - directly, thus preventing +warnings due to invalid configurations. + +You can achieve this by setting the source branch for a specific agent mapping to `LIVE`. +::: + +**Agent Mappings** can be used, in order to deliver specific configurations to agents. +They can also be used to define precisely which files and from which branch an agent should receive. + +![Configuration Server Workspace Architecture](assets/configuration-server-branches.png) + +## Promoting Files + +Changes to configuration files or agent mappings by users only affect the `WORKSPACE` branch. +If a user wants to make a change to a configuration file, but the version of the `LIVE` branch is delivered to the agent, +the user must do the following: + +* First, the user must perform the change, which allows the change to be tracked on the workspace branch. +* Afterwards the change must be approved and promoted by a user who has promotion rights. Only through promotion the changes to a file will be transferred to the `LIVE` branch. + +:::note +It is important to note that only whole files and not individual changes can be promoted. This means that if two different users have edited a single file it is only possible to promote the whole file and not just the changes of a specific user. +::: + +In the following screenshot, the configuration server's promotion user interface is shown. It can be used to review, approve and promote configurations. Only users who have promotion rights can approve and promote configuration files. + +![Configuration Server's promotion UI](assets/configuration-server-promotion-ui.png) + +1. The promotion UI can be access via the navigation sidebar. +2. The UI shows a list of all files which have been changed on the `WORKSPACE` branch, thus, differ from the `LIVE` branch. The icons show whether a file has been newly created, edited or deleted. Approved files that will be promoted to the `LIVE` branch are highlighted in green with a check mark. +3. The current version of the file on the `LIVE` branch. +4. The current version of the file on the `WORKSPACE` branch. +5. Button to promote the approved files. +6. The selected file can be approved with this button. + +## Four-Eyes Promoting Restriction + +By default, any user with promotion rights can promote any changes. +In some setups it can be beneficial to enforce peer-reviews before promoting changes. +The configuration server offers a mechanism to enforce a four eyes principle for changes which can be enabled using the following setting: + +```YAML +inspectit-config-server: + security: + four-eyes-promotion: true +``` + +When this setting is enabled, users with promotion rights will no longer be able to promote their own changes. + +:::note +This restriction is only applied to non-admin users! Users with admin rights will still be able to promote their own changes. +::: + +## Git-Authors +Every change has an author consisting of the login and an e-mail address of the user who made the change. For +ldap-users the login and e-mail address of the ldap account is used. +
+For internal users however, an e-mail address is generated. This address consists of the user's login and an e-mail +suffix. The default suffix is `@inspectit.rocks`. +
+You can provide a custom mail suffix in the following settings: +```YAML +inspectit-config-server: + mail-suffix: @my_mail.com +``` + +## External Changes + +While it is not recommended, it is possible to directly change the files in the filesystem instead of via the +configuration server's UI or REST-API. + +In order for your changes in the file-system to become active, you need to let the configuration server know about the external changes. +This can be done by sending an HTTP GET request to the `/api/v1/configuration/reload` endpoint. This request needs to include your credentials via basic auth. +A request to this endpoint causes all external changes to be committed to the `WORKSPACE` branch and the server to be updated accordingly. + +Alternatively, you can also manually commit to the `WORKSPACE` branch in the working directory of the configuration server. +However, you need to make sure that the server is either shut down or you need to have the guarantee that no other users are currently editing files via the UI, +otherwise your repository might get corrupted. diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/configuration-sources.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/configuration-sources.md new file mode 100644 index 0000000000..96384565ac --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/configuration-sources.md @@ -0,0 +1,97 @@ +--- +id: version-2.6.0-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.0.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.0.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.0.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.0.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.0/configuration/open-census-configuration.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/open-census-configuration.md new file mode 100644 index 0000000000..2f44ddbe26 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/open-census-configuration.md @@ -0,0 +1,35 @@ +--- +id: version-2.6.0-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.0 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.0/configuration/open-telemetry-configuration.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/open-telemetry-configuration.md new file mode 100644 index 0000000000..ef1bb93f23 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/configuration/open-telemetry-configuration.md @@ -0,0 +1,37 @@ +--- +id: version-2.6.0-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.0 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.0/getting-started/installation.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/getting-started/installation.md new file mode 100644 index 0000000000..f581cbe882 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/getting-started/installation.md @@ -0,0 +1,159 @@ +--- +id: version-2.6.0-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.0.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.0.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.0.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.0.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.0/getting-started/quick-start.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/getting-started/quick-start.md new file mode 100644 index 0000000000..dd6c0f71a3 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/getting-started/quick-start.md @@ -0,0 +1,22 @@ +--- +id: version-2.6.0-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.0/inspectit-ocelot-agent-2.6.0.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.0.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.0/instrumentation/process.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/instrumentation/process.md new file mode 100644 index 0000000000..ad100215bf --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/instrumentation/process.md @@ -0,0 +1,97 @@ +--- +id: version-2.6.0-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.0.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.0.jar" -jar my-java-program.jar +``` diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/metrics/tag-guard.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/metrics/tag-guard.md new file mode 100644 index 0000000000..392be3e42b --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/metrics/tag-guard.md @@ -0,0 +1,99 @@ +--- +id: version-2.6.0-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 a 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.0/tracing/tracing.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/tracing/tracing.md new file mode 100644 index 0000000000..136397bd8f --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.6.0/tracing/tracing.md @@ -0,0 +1,159 @@ +--- +id: version-2.6.0-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 retarted. +::: +### 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/versioned_sidebars/version-2.6.0-sidebars.json b/inspectit-ocelot-documentation/website/versioned_sidebars/version-2.6.0-sidebars.json new file mode 100644 index 0000000000..07f3c30998 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_sidebars/version-2.6.0-sidebars.json @@ -0,0 +1,68 @@ +{ + "version-2.6.0-docs": { + "Getting Started": [ + "version-2.6.0-doc1", + "version-2.6.0-getting-started/quick-start", + "version-2.6.0-getting-started/docker-examples", + "version-2.6.0-getting-started/installation" + ], + "Configuration": [ + "version-2.6.0-configuration/configuration-sources", + "version-2.6.0-configuration/external-configuration-sources", + "version-2.6.0-configuration/logging-configuration", + "version-2.6.0-configuration/open-census-configuration", + "version-2.6.0-configuration/plugin-configuration", + "version-2.6.0-configuration/agent-command-configuration" + ], + "Metrics": [ + "version-2.6.0-metrics/metrics", + "version-2.6.0-metrics/metric-recorders", + "version-2.6.0-metrics/metric-exporters", + "version-2.6.0-metrics/common-tags", + "version-2.6.0-metrics/custom-metrics", + "version-2.6.0-metrics/self-monitoring", + "version-2.6.0-metrics/tag-guard" + ], + "Tracing": [ + "version-2.6.0-tracing/tracing", + "version-2.6.0-tracing/trace-exporters", + "version-2.6.0-tracing/log-correlation", + "version-2.6.0-tracing/privacy", + "version-2.6.0-tracing/tracing-self-monitoring" + ], + "Tags": [ + "version-2.6.0-tags/tags-exporters" + ], + "Instrumentation": [ + "version-2.6.0-instrumentation/instrumentation", + "version-2.6.0-instrumentation/scopes", + "version-2.6.0-instrumentation/rules", + "version-2.6.0-instrumentation/code-style", + "version-2.6.0-instrumentation/special-sensors", + "version-2.6.0-instrumentation/process" + ], + "End User Monitoring": [ + "version-2.6.0-enduser-monitoring/enduser-monitoring-server", + "version-2.6.0-enduser-monitoring/eum-server-setup", + "version-2.6.0-enduser-monitoring/eum-server-configuration", + "version-2.6.0-enduser-monitoring/install-eum-agent" + ], + "Configuration Server": [ + "version-2.6.0-config-server/overview", + "version-2.6.0-config-server/cs-configuration", + "version-2.6.0-config-server/managing-files", + "version-2.6.0-config-server/files-staging", + "version-2.6.0-config-server/agent-mappings", + "version-2.6.0-config-server/scope-wizard", + "version-2.6.0-config-server/class-browser", + "version-2.6.0-config-server/user-authentication", + "version-2.6.0-config-server/config-docs", + "version-2.6.0-config-server/log-config", + "version-2.6.0-config-server/syntax-highlighting", + "version-2.6.0-config-server/status-table-view" + ], + "Breaking Changes": [ + "version-2.6.0-breaking-changes/Breaking Changes" + ] + } +} diff --git a/inspectit-ocelot-documentation/website/versions.json b/inspectit-ocelot-documentation/website/versions.json index a0c8d08b8c..54f9e8b703 100644 --- a/inspectit-ocelot-documentation/website/versions.json +++ b/inspectit-ocelot-documentation/website/versions.json @@ -1,4 +1,5 @@ [ + "2.6.0", "2.5.6", "2.5.5", "2.5.4",