From 7d1b203cf0ac786450082c8aa116956cccfbb467 Mon Sep 17 00:00:00 2001 From: NTTechnicalUser Date: Mon, 9 Oct 2023 13:16:32 +0000 Subject: [PATCH] Publish documentation for release 2.5.5 --- .../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.5.5/instrumentation/process.md | 97 ++++++ .../version-2.5.5/tags/tags-exporters.md | 293 ++++++++++++++++++ .../website/versions.json | 1 + 8 files changed, 741 insertions(+) create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/configuration-sources.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/open-census-configuration.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/open-telemetry-configuration.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/getting-started/installation.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/getting-started/quick-start.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/instrumentation/process.md create mode 100644 inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/tags/tags-exporters.md diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/configuration-sources.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/configuration-sources.md new file mode 100644 index 0000000000..719ba6678f --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/configuration-sources.md @@ -0,0 +1,97 @@ +--- +id: version-2.5.5-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.5.5.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.5.5.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.5.5.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.5.5.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.5.5/configuration/open-census-configuration.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/open-census-configuration.md new file mode 100644 index 0000000000..4a241ac9ad --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/open-census-configuration.md @@ -0,0 +1,35 @@ +--- +id: version-2.5.5-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.5.5 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.5.5/configuration/open-telemetry-configuration.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/open-telemetry-configuration.md new file mode 100644 index 0000000000..56432709ad --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/configuration/open-telemetry-configuration.md @@ -0,0 +1,37 @@ +--- +id: version-2.5.5-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.5.5 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.5.5/getting-started/installation.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/getting-started/installation.md new file mode 100644 index 0000000000..1054134fc1 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/getting-started/installation.md @@ -0,0 +1,159 @@ +--- +id: version-2.5.5-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.5.5.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.5.5.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.5.5.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.5.5.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.5.5/getting-started/quick-start.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/getting-started/quick-start.md new file mode 100644 index 0000000000..e9f76430eb --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/getting-started/quick-start.md @@ -0,0 +1,22 @@ +--- +id: version-2.5.5-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.5.5/inspectit-ocelot-agent-2.5.5.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.5.5.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.5.5/instrumentation/process.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/instrumentation/process.md new file mode 100644 index 0000000000..252d8f3d9c --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/instrumentation/process.md @@ -0,0 +1,97 @@ +--- +id: version-2.5.5-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.5.5.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.5.5.jar" -jar my-java-program.jar +``` diff --git a/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/tags/tags-exporters.md b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/tags/tags-exporters.md new file mode 100644 index 0000000000..5c9d95b309 --- /dev/null +++ b/inspectit-ocelot-documentation/website/versioned_docs/version-2.5.5/tags/tags-exporters.md @@ -0,0 +1,293 @@ +--- +id: version-2.5.5-tags-exporters +title: Tags Exporters +original_id: tags-exporters +--- + +Tags exporters represent special exporters of InspectIT, which allow to export internal tags to external applications like browsers. +Currently, there is only one tags exporter: + +| Exporter |Supports run-time updates| Push / Pull |Enabled by default| +|---------------------------------|---|-------------|---| +| [HTTP Exporter](#http-exporter) |Yes| Push & Pull |No| + +## HTTP Exporter + +The HTTP exporter exports tags via a REST-API running on an HTTP-server. The server provides two endpoints. +One GET-endpoint to expose data to external applications and one PUT-endpoint to receive data from external applications. +The server is by default started on the port `9000` and data can then be accessed or written by +calling 'http://localhost:9000/inspectit' + +#### Production environment + +The Tags HTTP exporter does not provide any encryption of data and does not perform any authentication. +Thus, this server should not be exposed directly to the public in a production environment. +It is recommended to set up a proxy in front of this server, which handles encryption and authentication. + +Furthermore, please make sure to enable port forwarding, if you use servlet-containers like tomcat. +You should also set _-Dinspectit.expoters.tags.http.host=0.0.0.0_ as parameter in the tomcat start configuration. + +Additionally, make sure that your firewall is not blocking the HTTP-server address. + +The server performs authorization with checking, whether the request origin is allowed to access the server. +Additionally, every request has to provide a session-ID to access their own session data. + +#### Session identification + +Data tags will always be stored behind a provided session-ID to ensure data correlation with its browser. +The session-ID will be read from a specific request-header. The _**session-id-header**_-property in the HTTP-exporter allows +to specify, which exact header should be used to read the session-ID from. + +The default-instrumentation of InspectIT will check the specified _session-id-header_ for a valid session-ID. +Thus, there is no additional configuration necessary to read session-ID from HTTP-headers. + +Behind every session-ID, there is a data storage containing all data tags for this session, as long as they are enabled for browser propagation. +These data storages can only be created, by sending requests to the target application, which the Ocelot-agent is attached to. +You cannot create new data storages for example by pushing data into the HTTP-server by using the API. +If a request to the REST-API contains a session-ID, which does not exist in InspectIT, the API will always return 404. + +The HTTP-exporter can only store a specific amount of sessions, which can be configured in the configuration server. +Sessions will be deleted after their _time-to-live_ is expired. Their time-to-live will be reset everytime a request +the HTTP-server receives a successful request. + +#### Session limits + +There are some limitations for every session to prevent excessive memory consumption. +The length of the session-ID is restricted to a minimum of 16 characters and a maximum of 512 characters. +Furthermore, every session is able to contain up to **128 data keys**. +The maximum length for data keys are **128 chars**. The maximum length for data values are **2048 chars**. + +#### Runtime Updates + +All properties of the HTTP-exporter can be updated during runtime. However, changing properties will result in a server +restart, which also deletes all data currently stored in the server. + +The following properties are nested properties below the `inspectit.exporters.tags.http` property: + +| Property | Default | Description | +|----------------------|--------------|-------------------------------------------------------------------------------------------------------------| +| `.enabled` | `DISABLED` | If `ENABLED` or `IF_CONFIGURED`, the inspectIT Ocelot agent will try to start the exporter and HTTP server. | +| `.host` | `127.0.0.1` | The hostname or network address to which the HTTP server should bind. | +| `.port` | `9000` | The port the HTTP server should use. | +| `.path` | `/inspectit` | The path on which the HTTP endpoints will be available. | +| `.allowed-origins` | `["*"]` | A list of allowed origins, which are able to access the http-server. | +| `.session-limit` | `100` | How many sessions can be stored in the server at the same time. | +| `.session-id-header` | `Session-Id` | The header, which will be read during propagation to extract the session-ID from | +| `.time-to-live` | `300` | How long sessions should be stored in the server in seconds. | + +The data of the HTTP exporter is stored inside internal data storages. Data tags will only be written to the storage, +if they are enabled for [browser propagation](../instrumentation/rules.md#data-propagation). + +### Client Example + +This example should demonstrate, how you can call the REST-API in your frontend application. + +```javascript +// Send some requests to transfer the session-id to inspectIT +callBackend(); + +// Send GET-request +getTags(); + +// Send PUT-request +putTags(); + + +function getTags() { + const xhr = new XMLHttpRequest(); + const url = "http://localhost:9000/inspectit"; + + xhr.open("GET", url); + xhr.setRequestHeader("Session-Id", "my-very-awesome-session-id"); + + xhr.onreadystatechange = () => { + if (xhr.readyState === XMLHttpRequest.DONE) { + if (xhr.status === 200) { + let receivedData = xhr.responseText; // Read received data + console.info(receivedData); + } else { + console.error("Error fetching data: ", xhr.status); + } + } + }; + xhr.send(); +} + +function putTags() { + const data = [ + {"service": "test-01"}, {"url": "www.example.com"} + ] + const xhr = new XMLHttpRequest(); + const url = "http://localhost:9000/inspectit"; + + xhr.open("PUT", url); + xhr.setRequestHeader("Session-Id", "my-very-awesome-session-id"); + + xhr.onreadystatechange = () => { + if (xhr.readyState === XMLHttpRequest.DONE) { + if (xhr.status === 200) { + console.log("Data fetched successfully!"); + } else { + console.error("Error fetching data: ", xhr.status); + } + } + }; + xhr.send(JSON.stringify(data)); +} +``` + +### OpenAPI documentation + +Below you can see the OpenAPI documentation for the REST-API in YAML-format: + +```yaml +openapi: 3.0.0 +info: + title: Tags Http Exporter + description: | + The API provides access to data tags, which are stored on the Tags HTTP-server of a InspectIT-java-agent. One data tag consists of a key-value-pair. + Data Tags will be stored in the server, if they are enabled for browser-propagation in the InspectIT configuration server. + Using the API, those tags can be read, written and overwritten. However, every data tag will be stored behind a session-ID by InspectIT. + + In order to use a session-ID for storing data tags, a request has to been sent to the target application, which the InspectIT-java-agent is attached to. + This request should contain the session-ID in it's headers. + All data tags created by this request, will be stored behind the provided session-ID as long as they are enabled for browser-propagation. + + To access specific data tags on the server via this API, requests will also need to contain the corresponding session-ID inside their header. + Which header should be used to read the session-ID, can be configured in the InspectIT configuration server. By default, the header "Session-Id" will be used. + Data tags are only cached for a specific amount of time, which is also defined in the InspectIT configuration server. + contact: + name: Novatec-Consulting GmbH + url: https://inspectit.rocks/ + email: vhv-team@novatec-gmbh.de + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + version: 1.0.0 +servers: + - url: http://localhost:9000/inspectit + description: default-URL of the API. However, the host, port and path can be configured in the InspectIT configuration-server +paths: + /inspectit: + summary: Single path of the API + description: Single path of the API, which can be configured in the InspectIT configuration-server + get: + summary: Read currently stored data tags + description: | + Provides all currently stored data tags for the specified session in the session-ID. data tags will be returend as a set of map-entries. + Data tags will only be stored in the tags-server, if they are enabled for browser-propagation. + + Note that all data tags are only cached for a specific amount of time, which can be configured in the InspectIT configuration server. + parameters: + - name: Session-Id + in: header + description: | + Custom header with the ID of the current session. The session-ID-header-name can be configured in the InspectIT configuration-server. + By default, "Session-Id" will be used as the session-ID-header-name. + + The length of the session-id is restricted to a minimum of 16 characters and a maximum of 512 characters. + required: true + schema: + type: string + responses: + '200': + description: Success - Response contains all current data tags + content: + application/json: + schema: + type: array + items: + type: object + additionalProperties: + type: string + example: '[{"key1": "value1"}, {"key2": "value2"}]' + '400': + description: Failure - Missing session-ID-header + '403': + description: Forbidden - Not allowed CORS headers + '404': + description: Failure - Session-ID not found in session-ID-header + put: + summary: Write or overwrite data tags + description: | + Overwrites data tags that are already stored in the Tags HTTP-server for the specified session-ID. + Alternatively, write new data tags into the storage, to allow the InspectIT-java-agent to use tags, which are not available inside the JVM. + + However, new data tags can only be written, if there already exists a data tag storage for the provided session-ID. + It is not possible to create new data tag storages through this API, but only within the InspectIT-java-agent, by sending request to the target application. + + Note that these new data tags also have to be enabled for browser-propagation as well as down-propagation in the InspectIT configuration server. + parameters: + - name: Session-Id + in: header + description: | + Custom header with the ID of the current session. The session-ID-header-name can be configured in the InspectIT configuration-server. + By default, "Session-Id" will be used as the session-ID-header-name. + + The length of the session-id is restricted to a minimum of 16 characters and a maximum of 512 characters. + required: true + schema: + type: string + requestBody: + description: data tags should be written or overwritten + required: true + content: + application/json: + schema: + type: array + items: + type: object + additionalProperties: + type: string + example: '[{"key1": "value1"}, {"key2": "value2"}]' + responses: + '200': + description: Success - Data tags have been written + '400': + description: Failure - Invalid request body or missing session-ID-header + '403': + description: Forbidden - Not allowed CORS headers + '404': + description: Failure - Session-ID not found in session-ID-header + options: + summary: Cross-Origin safety check + description: | + Allows to send pre-flight-requests to the API before actual requests. The usage is voluntary. + parameters: + - name: Origin + in: header + required: true + schema: + type: string + - name: Access-Control-Request-Method + in: header + required: true + schema: + type: string + - name: Access-Control-Request-Headers + in: header + required: true + schema: + type: string + responses: + '200': + description: Success - Pre-flight response with CORS headers + headers: + Access-Control-Allow-Origin: + schema: + type: string + Access-Control-Allow-Methods: + schema: + type: string + Access-Control-Allow-Headers: + schema: + type: string + Access-Control-Allow-Credentials: + schema: + type: boolean + '403': + description: Forbidden - Missing required headers +externalDocs: + description: More information about the Exporter API + url: https://inspectit.github.io/inspectit-ocelot/docs/tags/tags-exporters +``` diff --git a/inspectit-ocelot-documentation/website/versions.json b/inspectit-ocelot-documentation/website/versions.json index 9d3ef6dcc1..d2ccd4d580 100644 --- a/inspectit-ocelot-documentation/website/versions.json +++ b/inspectit-ocelot-documentation/website/versions.json @@ -1,4 +1,5 @@ [ + "2.5.5", "2.5.4", "2.5.3", "2.5.2",