Skip to content

Commit 5fb430e

Browse files
NTTechnicalUserNTTechnicalUser
committed
[skip ci] Publish documentation v2.1.1
1 parent 7ee0fcb commit 5fb430e

File tree

6 files changed

+349
-0
lines changed

6 files changed

+349
-0
lines changed

‎inspectit-ocelot-documentation/website/versioned_docs/version-2.1.1/configuration/configuration-sources.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
id: version-2.1.1-configuration-sources
3+
title: Configuration Sources
4+
original_id: configuration-sources
5+
---
6+
7+
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.
8+
Internally it uses the Spring-based `PropertySource` order to allow overriding of configuration values.
9+
Configuration properties are considered in inspectIT Ocelot in the following order:
10+
11+
1. [Java Agent Arguments](#java-agent-arguments)
12+
1. [Java System Properties](#java-system-properties)
13+
1. [OS environment Variables](#os-environment-variables)
14+
1. External Configuration Sources:
15+
* [File-based Configuration](configuration/external-configuration-sources.md#file-based-configuration)
16+
1. inspectIT Ocelot Defaults
17+
18+
When an invalid configuration is given to inspectIT on startup, the agent will use a fallback configuration.
19+
In this fallback configuration, the agent is inactive with the exception of listening for configuration updates.
20+
21+
When giving an invalid configuration through a runtime update to the agent, the agent will simply retain the previous configuration.
22+
23+
## Available Configuration Sources
24+
25+
### Java Agent Arguments
26+
27+
You can pass a JSON object as string to the agent via its command line arguments.
28+
For example, to override the service name used to identify your application reporting the performance data,
29+
you can change the `inspectit.service-name` property as follows:
30+
31+
```bash
32+
$ java -javaagent:/path/to/inspectit-ocelot-agent-2.1.1.jar="{ \"inspectit\": { \"service-name\": \"My Custom Service\" }}" -jar my-java-program.jar
33+
```
34+
35+
Note that you have to escape the quotes within your JSON string. On linux you can just use the more readable single quotes notation:
36+
37+
```bash
38+
$ java -javaagent:/path/to/inspectit-ocelot-agent-2.1.1.jar='{ "inspectit": { "service-name": "My Custom Service" }}' -jar my-java-program.jar
39+
```
40+
41+
### Java System Properties
42+
43+
You can pass any configuration property as the Java System property to the Java command that you use to start your Java application.
44+
Using this approach you can change the `inspectit.service-name` property as follows:
45+
46+
```bash
47+
$ java -Dinspectit.service-name="My Custom Service" -javaagent:/path/to/inspectit-ocelot-agent-2.1.1.jar -jar my-java-program.jar
48+
```
49+
50+
### OS Environment Variables
51+
52+
Similar to the Java System properties, inspectIT Ocelot will also consider all the available operating system environment variables.
53+
Due to the relaxed bindings, you can use upper case format, which is recommended when using system environment variables.
54+
55+
```bash
56+
$ INSPECTIT_SERVICE_NAME="My Custom Service" java -javaagent:/path/to/inspectit-ocelot-agent-2.1.1.jar -jar my-java-program.jar
57+
```
58+
59+
## Relaxed Bindings
60+
61+
Note that due to the Spring-powered configuration approach, the inspectIT Ocelot agent uses Spring support for relaxed bindings.
62+
This means that a property can be specified in different formats depending on the property source.
63+
As suggested by Spring, the allowed formats are:
64+
65+
| Property | Note |
66+
| --- | --- |
67+
| `inspectit.service-name` | Kebab-case, which is recommended for use in `.properties` and `.yml` files. |
68+
| `inspectit.serviceName` | Standard camelCase syntax. |
69+
| `inspectit.service_name` | Underscore notation (snake_case), which is an alternative format for use in `.properties` and `.yml` files. |
70+
| `INSPECTIT_SERVICE_NAME` | UPPER_CASE format, which is recommended when using system environment variables. |
71+
72+
The formats should be used in the following way, based on the type of property source:
73+
74+
| Property Source | Format |
75+
| --- | --- |
76+
| System properties | Camel case, kebab case, or underscore notation. |
77+
| Environment Variables | Upper case format with the underscore as the delimiter. |
78+
| Property files (`.properties`) | Camel case, kebab case, or underscore notation. |
79+
| YAML files (`.yaml`, `.yml`) | Camel case, kebab case, or underscore notation. |
80+
81+
## Environment Information
82+
83+
Each agent stores the following information about its runtime environment:
84+
85+
| Property | Note |
86+
| --- | --- |
87+
| `inspectit.env.agent-dir` | Resolves to the path where the agent-jar is stored. |
88+
| `inspectit.env.hostname` | The hostname where the agent is running. |
89+
| `inspectit.env.pid` | The process id of the JVM process. |
90+
91+
They are used to define the default behavior when writing the configuration persistence file and will be sent
92+
as attributes to the configuration server when fetching the configuration.
93+
94+
You can reference these properties within the configuration using e.g. `${inspectit.env.agent-dir}`
95+
as shown in the default configuration for
96+
[HTTP-based configuration](configuration/external-configuration-sources.md#http-based-configuration).
97+
Referencing every other property follows the same schema.

‎inspectit-ocelot-documentation/website/versioned_docs/version-2.1.1/configuration/open-census-configuration.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
id: version-2.1.1-open-census-configuration
3+
title: Using OpenCensus Library with inspectIT Ocelot
4+
sidebar_label: OpenCensus Configuration
5+
original_id: open-census-configuration
6+
---
7+
8+
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.
9+
Following these rules will make sure that there are no run-time problems in your application.
10+
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.
11+
12+
1. Make sure you are using the same version of OpenCensus as inspectIT Ocelot.
13+
14+
The inspectIT Ocelot agent in version 2.1.1 internally uses OpenCensus in version 0.28.3. Please adapt any OpenCensus dependency in your application to this version to avoid run-time conflicts.
15+
```XML
16+
<dependency>
17+
<groupId>io.opencensus</groupId>
18+
<artifactId>opencensus-api</artifactId>
19+
<version>0.28.3</version>
20+
</dependency>
21+
```
22+
23+
2. Set the JVM property `inspectit.publishOpenCensusToBootstrap` to `true`.
24+
25+
```
26+
-Dinspectit.publishOpenCensusToBootstrap=true
27+
```
28+
29+
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.
30+
31+
3. Add the agent to the start of a JVM
32+
33+
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.
34+
35+
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.

‎inspectit-ocelot-documentation/website/versioned_docs/version-2.1.1/configuration/open-telemetry-configuration.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
id: version-2.1.1-open-telemetry-configuration
3+
title: Using OpenTelemetry Library with inspectIT Ocelot
4+
sidebar_label: OpenTelemetry Configuration
5+
original_id: open-telemetry-configuration
6+
---
7+
8+
><mark> 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
9+
</mark>
10+
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.
11+
Following these rules will make sure that there are no run-time problems in your application.
12+
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.
13+
14+
1. Make sure you are using the same version of OpenTelemetry as inspectIT Ocelot.
15+
16+
The inspectIT Ocelot agent in version 2.1.1 internally uses OpenTelemetry in version {opentelemetry-version}. Please adapt any OpenTelemetry dependency in your application to this version to avoid run-time conflicts.
17+
```XML
18+
<dependency>
19+
<groupId>io.opentelemetry</groupId>
20+
<artifactId>opentelemetry-api</artifactId>
21+
<version>{opentelemetry-version}</version>
22+
</dependency>
23+
```
24+
25+
2. Set the JVM property `inspectit.publishOpenTelemetryToBootstrap` to `true`.
26+
27+
```
28+
-Dinspectit.publishOpenTelemetryToBootstrap=true
29+
```
30+
31+
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.
32+
33+
3. Add the agent to the start of a JVM
34+
35+
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.
36+
37+
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.

‎inspectit-ocelot-documentation/website/versioned_docs/version-2.1.1/getting-started/installation.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
id: version-2.1.1-installation
3+
title: Installation
4+
original_id: installation
5+
---
6+
7+
This section describes the installation details for the inspectIT Ocelot agent.
8+
9+
## Supported Java Runtime Environments
10+
11+
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.
12+
The agent works with different JRE distributions including Oracle, openJDK, Azul, etc.
13+
14+
## Adding the Agent to a JVM
15+
16+
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.
17+
This way the agent will be initialized before your application starts.
18+
19+
```bash
20+
$ java -javaagent:"/path/to/inspectit-ocelot-agent-2.1.1.jar" -jar my-java-program.jar
21+
```
22+
23+
> 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.
24+
25+
## Attaching the Agent to a Running JVM
26+
27+
inspectIT Ocelot also supports attaching the agent to an already running JVM.
28+
In such a scenario the collection of metrics and traces will start from the point of the attachment.
29+
30+
The attaching can easily be done using the agent itself and executing the following command:
31+
32+
```bash
33+
$ java -jar inspectit-ocelot-agent-2.1.1.jar <PID> [<AGENT_ARGUMENTS>]
34+
```
35+
36+
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:
37+
```bash
38+
$ java -jar inspectit-ocelot-agent-2.1.1.jar 1337 '{"inspectit":{"service-name":"my-agent"}}'
39+
```
40+
41+
> The agent is internally using the utility [jattach](https://github.com/apangin/jattach) for attaching itself to a running JVM.
42+
43+
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:
44+
45+
```bash
46+
$ jcmd -l
47+
```
48+
49+
### Attaching Using jattach
50+
51+
Another way of attaching the agent to a running JVM is to use the utility [jattach](https://github.com/apangin/jattach):
52+
53+
```bash
54+
$ ./jattach.sh <PID> load instrument false /path/to/inspectit-ocelot-agent-2.1.1.jar='{"inspectit.service-name" : "MyService"}'
55+
```
56+
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.
57+
58+
> 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.
59+
60+
## Using the Agent With a Security Manager
61+
62+
If a Java Security Manager is enabled, the agent needs to be granted additional permissions to work.
63+
For this, add the following to your policy file:
64+
65+
```
66+
grant codeBase "file:<absolute_path_to_inspectit-ocelot-agent.jar>" {
67+
permission java.security.AllPermission;
68+
};
69+
```
70+
71+
The correct policy file location depends on different factors.
72+
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.
73+
74+
## Using the Agent with Kubernetes
75+
76+
There are several ways to use the agent in a Kubernetes cluster.
77+
For example, you could integrate the agent directly into the application container images, but this requires customizing all images.
78+
79+
Another possibility is that the agent is automatically injected into the application containers using an **operator** and attached to the JVM processes.
80+
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.
81+
It is still under development, so it is not feature-complete, but depending on your needs the current version could already provide everything needed.
82+
83+
:::warning Up-to-dateness of the Documentation
84+
Since the OpenTelemetry K8s operator is currently under heavy development, the installation steps described below **may be outdated**.
85+
They may nevertheless be helpful in navigating the OpenTelemetry Operator installation documentation by showing you which parts you need.
86+
:::
87+
88+
### Installing the Operator
89+
90+
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:
91+
92+
1. Install the [cert-manager](https://cert-manager.io/docs/installation/) in your cluster if you have not done it already.
93+
2. Install the operator using the following command. Please note that this will install the latest version of it:
94+
95+
```shell
96+
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
97+
```
98+
99+
By adjusting the URL to a different GitHub release, a specific version of the operator can be used:
100+
101+
```shell
102+
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v{version}/opentelemetry-operator.yaml
103+
```
104+
105+
### Using the Operator
106+
107+
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:
108+
109+
:::note
110+
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.
111+
:::
112+
113+
```yaml
114+
apiVersion: opentelemetry.io/v1alpha1
115+
kind: Instrumentation
116+
metadata:
117+
name: my-instrumentation
118+
spec:
119+
java:
120+
image: inspectit/inspectit-ocelot-agent:1.15.2
121+
```
122+
123+
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:
124+
125+
- `true` - inject the `Instrumentation` resource from the namespace.
126+
- `my-instrumentation` - name of Instrumentation CR instance.
127+
- `false` - do not inject
128+
129+
The following annotation can be used for this:
130+
```yaml
131+
instrumentation.opentelemetry.io/inject-java: "true"
132+
```
133+
134+
:::warning Ensure Correct Referencing
135+
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!
136+
:::
137+
138+
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.
139+
140+
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:
141+
142+
```yaml
143+
containers:
144+
- image: my-app-image
145+
name: my-app
146+
env:
147+
- name: INSPECTIT_CONFIG_HTTP_URL
148+
value: http://my-ocelot-config-server:8090/api/v1/agent/configuration
149+
- name: INSPECTIT_SERVICE_NAME
150+
value: my-service-name
151+
```
152+
153+
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.
154+
155+
4. Start or restart the containers to trigger the injection and attachment of the agent.
156+
157+
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)).

‎inspectit-ocelot-documentation/website/versioned_docs/version-2.1.1/getting-started/quick-start.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
id: version-2.1.1-quick-start
3+
title: Quick Start
4+
original_id: quick-start
5+
---
6+
7+
You can find and download all released versions of inspectIT Ocelot in our [GitHub](https://github.com/inspectIT/inspectit-ocelot/releases) repository.
8+
You can get the current version on the following link:
9+
10+
```bash
11+
$ wget https://github.com/inspectIT/inspectit-oce/releases/download/2.1.1/inspectit-ocelot-agent-2.1.1.jar
12+
```
13+
14+
The best way to start using inspectIT Ocelot is to attach the Java agent when starting your Java program.
15+
Use the `-javaagent` command-line option to reference the inspectIT Ocelot jar:
16+
17+
```bash
18+
$ java -javaagent:"/path/to/inspectit-ocelot-agent-2.1.1.jar" -jar my-java-program.jar
19+
```
20+
21+
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.
22+
In the [Configuration](configuration/configuration-sources.md) section you can find more details on how to configure the inspectIT Ocelot agent.

‎inspectit-ocelot-documentation/website/versions.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[
2+
"2.1.1",
23
"1.16.1",
34
"2.1.0",
45
"2.0.3",

0 commit comments

Comments
 (0)