Publish documentation for release 2.6.2

inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/agent-mappings.md

@@ -0,0 +1,96 @@
+---
+id: version-2.6.2-agent-mappings
+title: Agent Mappings
+original_id: agent-mappings
+---
+
+Agent mappings are used to determine which agent receives which configuration. Here, individual files or specific 
+folders can be defined, which serve as the basis for the resulting configuration. 
+Furthermore, you can specify which branch (`WORKSPACE` or `LIVE`) the mapping should use to obtain the configuration files.
+
+It's important to note that the first matching agent mapping will be used to determine which configuration is shipped to an agent.
+Additional agent mappings which may also match the attributes list sent by an agent will be ignored.
+See section [HTTP-based Configuration](configuration/external-configuration-sources.md#http-based-configuration) for
+information on how to specify which attributes will be sent by an agent.
+
+An agent mapping consists of the following properties:
+
+| Property | Default | Note |
+| --- | --- | --- |
+| `name` | - | The name of the agent mapping. |
+| `sources` | `[]` | A list of paths. All configuration files matching this list (Directories are resolved recursively) will be merged together and returned to matching agents. |
+| `attributes` | `{}` | A map of attributes. This map is used to determine whether an agent will match this agent mapping, thus, get its configuration. |
+| `sourceBranch` | `WORKSPACE` | Defines which branch is used as source for the configuration files. Supported values are: `WORKSPACE`, `LIVE` |
+
+
+The configuration server is shipped with a default agent mapping.
+This default agent mapping maps each agent to each configuration file of the `workspace` branch.
+
+```YAML
+- name: "Default Mapping"
+  sources:
+  - "/"
+  attributes:
+    service: ".*"
+  sourceBranch: "WORKSPACE"
+```
+
+## Git Staging
+
+:::tip
+You can find more detailed information about file staging and promotion [here](config-server/files-staging.md).
+:::
+
+Since the version `2.6.0` the configuration for the agent mappings itself will also be included into the git staging. For all agent mappings 
+the configuration is stored in one file. After one or several agent mappings have been edited, the changes will also
+appear on the promotion page. The promotion of the agent mappings configuration works directly like the promotion of agent configuration files.
+
+Additionally, it is possible to select a source branch (`WORKSPACE` or `LIVE`) for the agent mappings configuration itself. 
+This will determine, whether changes in the agent mappings should be applied directly or only after the promotion of the 
+agent mappings configuration.
+
+:::important
+The source branch for the agent mappings configuration will **not affect** the defined `sourceBranch` in each **individual agent mapping**!
+The `sourceBranch` property of an individual agent mapping determines, which branch should be used for the agent configuration files.
+:::
+
+![Different Source Branches on Agent Mappings Page](assets/agent_mappings_source_branch.png)
+
+You can define, which source branch should be used at start-up for the agent mappings
+in the application properties of the configuration server:
+
+```YAML
+inspectit-config-server:
+  initial-agent-mappings-source-branch: WORKSPACE
+```
+
+## Example Agent Mappings
+
+### Example 1
+
+The following agent mapping will deliver all promoted configuration files located in the directory `/common` and `/europe/west` to all agents whose `region` attributes is equal to `eu-west`.
+
+```YAML
+- name: "Example Mapping 1"
+  sources:
+  - "/common"
+  - "/europe/west"
+  attributes:
+    service: ".*"
+    region: "eu-west"
+  sourceBranch: "LIVE"
+```
+
+### Example 2
+
+The following agent mapping will deliver all configuration files located in the directory `/common` and the specific file `/special/customer-service.yml` of the `workspace` branch to all agents whose `service` attributes is equal to `customer-service`.
+
+```YAML
+- name: "Example Mapping 2"
+  sources:
+  - "/common"
+  - "/special/customer-service.yml"
+  attributes:
+    service: "customer-service"
+  sourceBranch: "WORKSPACE"
+```

inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/config-docs.md

@@ -0,0 +1,116 @@
+---
+id: version-2.6.2-config-docs
+title: Configuration Docs
+original_id: config-docs
+---
+
+Since version `1.15.0` the inspectIT Ocelot configuration server provides the option to look at documentation for 
+instrumentation objects, i.e. scopes, rules and actions, as well as metrics from the perspective of a selected agent mapping.
+
+## Using existing Configuration Docs
+
+To open the sidebar for the documentation, click on the `Configuration Docs`-button to the right of the configuration editor.
+
+![Picture of opened Configuration Docs view](assets/config-docs-button.png)
+
+Then select an agent mapping, for which the documentation should be shown, from the Dropdown menu. 
+They are alphabetically ordered, and can be filtered using the search box.
+
+![Picture of agent mapping dropdown](assets/config-docs-dropdown.png)
+
+You can also decide if you want to include the **default configuration** that is shipped with the agent by default in the documentation.
+The checkbox below can be used to turn this on or off.
+
+The documentation for the selected agent mapping will then be shown below.
+It updates whenever you change either of the settings at the top, or save changes to a configuration file in the editor.
+
+To help with searching documentation for specific objects, you can filter the documentation using the filter text box above.
+
+![Picture of documentation filtered for 'attach'](assets/config-docs-filter.png)
+
+Since version `2.6.2` the files, where a specific object is defined, are also tracked.
+If an object is only used or mentioned in a configuration file, the file will not be shown in the particular object documentation.
+
+If you click on a specific file path in an object documentation, the configuration file, which defines the object will be opened.
+
+
+## Writing your own Configuration Docs
+
+Part of the documentation is automatically created based on the attributes of each instrumentation object, so there will be some documentation for your own configurations without additional effort.
+However, this is of course limited, so to make full use of the feature, you should extend them as described in the following.
+
+:::tip
+See also the chapter regarding [Configuration Code Style](instrumentation/code-style.md) for an overview of recommendations on how documentation should be structured. 
+:::
+
+### Common Documentation Attributes
+
+With all three kinds of instrumentation objects documentation is added below the key `docs`.
+Depending on the type of the instrumentation object there are more or less documentation attributes that can be set.
+
+For scopes and rules the following attributes are all options, for actions there a few more.
+
+#### Attribute: Description
+
+With the key `description`, you can provide a general description of what the instrumentation object is for, what it does or how it works.
+
+Multiline Strings within the description will be in the actual documentation with all the linebreaks, indents, etc. that you put into them. 
+Wrapping of lines that are too long for the documentation view will happen automatically. 
+Therefore, you should avoid putting linebreaks within sentences, it could lead to seemingly random linebreaks in the actual documentation view. 
+It is implemented that way, so you can use group the description into paragraphs or express something more specific, e.g. describe what an input of type Map should look like by writing an example as YAML into the description.  
+
+#### Attribute: Since
+
+With the key `since` you can add a versioning tag as a string that will also be shown in the documentation.
+
+#### Example
+
+The documentation for a rule could then for example look like the following:
+
+```YAML
+[...]
+  rules:
+    'r_new_rule':
+      docs:
+        description: |
+          Captures execution time of current method.
+          The capturing will only happen if xy is true.
+        since: '1.42.0'
+      [...]
+```
+
+### Special Documentation Attributes for Actions
+
+For actions there are two more possible keys below `docs`.
+
+#### Attribute: Inputs
+
+One is `inputs` below which you can add any input names as keys and a description for them as values.
+
+For **special input parameters** (see [Input Parameters](instrumentation/rules.md#input-parameters) for further info) the description is **added automatically**, so you do not have to add any yourself.
+
+#### Attribute: Return-Value
+
+The other is `return-value` which should contain a description of the return value, if there is any.
+
+#### Example
+
+An action with a full documentation could look like the following:
+
+```YAML
+[...]
+  actions:
+    'a_attachment_get':
+      docs:
+        description: 'Reads a given attachment from a target object.'
+        inputs:
+          'target': 'Object from which the attachment should be read.'
+          'key': 'Key for attachment that should be read.'
+        return-value: 'The value of the wanted attachment for the given object.'
+        since: '1.42.0'
+      input:
+        '_attachments': 'ObjectAttachments'
+        'target': 'Object'
+        'key': 'String'
+      value: '_attachments.getAttachment(target, key)'
+```

inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/overview.md

@@ -0,0 +1,23 @@
+---
+id: version-2.6.2-overview
+title: Configuration Server Overview
+sidebar_label: Overview
+original_id: overview
+---
+
+The *inspectIT Configuration Server* is a standalone component provided by the inspectIT Ocelot project.
+It can be used to centrally manage and distribute the inspectIT Ocelot agent configuration files.
+For this purpose, HTTP endpoints are provided that can be queried by the agents to obtain the corresponding configuration.
+This has the advantage that the manual administration of the configuration files is not required.
+
+![Configuration Server Architecture](assets/configuration-server-architecture.png)
+
+The server provides a web interface to manage all relevant settings and configurations. It can be accessed via `http://<server-address>:<port>/ui/`. By default, the configuration server is listening to port `8090`.
+
+In addition, a Swagger UI is provided which contains a list including documentation of the server's REST API. By default, the Swagger UI can be accessed via `http://<server-address>:<port>/swagger-ui.html`.
+
+## Management of Configuration Files
+
+Since version `1.4`, the configuration server uses Git and a local repository to manage the working directory. If a working directory already exists that was created by a configuration server in version `1.3` or lower, it is automatically migrated to a working directory managed using a local Git repository. No manual adjustments are necessary.
+
+Please see [Managing Files](managing-files.md) for more information on managing of the configuration files.

inspectit-ocelot-documentation/website/versioned_docs/version-2.6.2/config-server/status-table-view.md

@@ -0,0 +1,21 @@
+---
+id: version-2.6.2-status-table-view
+title: Status Table View Guide
+sidebar_label: Agent Status Table View
+original_id: status-table-view
+---
+
+The Status Table in the Agent Status page offers, in addition to displaying the most important agent information in the table, the possibility to retrieve additional information via different buttons.
+Here is a short guide to help you navigate around the status table.
+
+![Status Table View](assets/status-table-view-ui.png)
+
+## Explanation of Highlighted Buttons
+
+| Button                                                                          | Function                                                                                                                                                                                                                                                    |
+|---------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ![Status Table View](assets/service-states-btn.png)<br /> **Service States**    | Displays the services (e.g. Prometheus, Jaeger, Influx, Log-Preloading, Agent Command Service, ...) and their current state (`enabled`/`disabled`).<br />In the future, we plan to implement the functionality to enable/disable the services in this view. |
+| ![Status Table View](assets/logs-btn.png)<br /> **Agent Logs**                  | Displays the logs of the service if agent commands and log preloading are enabled.                                                                                                                                                                          |
+| ![Status Table View](assets/config-btn.png)<br /> **Current Config**            | Displays the current config in `yaml` format when the agent commands are enabled.                                                                                                                                                                           |
+| ![Status Table View](assets/agent-health-icon.png)<br /> **Agent State**        | Displays the current agent state and the latest agent health incidents.                                                                                                                                                                                     |
+| ![Status Table View](assets/download-archive-btn.png)<br /> **Support Archive** | Downloads a support archive as a `.zip` file if the agent commands are enabled. The support archive contains logs (if log preloading is enabled), the current config, and environment details.                                                              |

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

@@ -0,0 +1,97 @@
+---
+id: version-2.6.2-configuration-sources
+title: Configuration Sources
+original_id: configuration-sources
+---
+
+inspectIT Ocelot tries to implement the zero-configuration approach but lets you externalize the configuration and influence every bit of its configuration if this is required.
+Internally it uses the Spring-based `PropertySource` order to allow overriding of configuration values.
+Configuration properties are considered in inspectIT Ocelot in the following order:
+
+1. [Java Agent Arguments](#java-agent-arguments)
+1. [Java System Properties](#java-system-properties)
+1. [OS environment Variables](#os-environment-variables)
+1. External Configuration Sources:
+    * [File-based Configuration](configuration/external-configuration-sources.md#file-based-configuration)
+1. inspectIT Ocelot Defaults
+
+When an invalid configuration is given to inspectIT on startup, the agent will use a fallback configuration.
+In this fallback configuration, the agent is inactive with the exception of listening for configuration updates.
+
+When giving an invalid configuration through a runtime update to the agent, the agent will simply retain the previous configuration.
+
+## Available Configuration Sources
+
+### Java Agent Arguments
+
+You can pass a JSON object as string to the agent via its command line arguments.
+For example, to override the service name used to identify your application reporting the performance data,
+you can change the `inspectit.service-name` property as follows:
+
+```bash
+$ java -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar="{ \"inspectit\": { \"service-name\": \"My Custom Service\" }}" -jar my-java-program.jar
+```
+
+Note that you have to escape the quotes within your JSON string. On linux you can just use the more readable single quotes notation:
+
+```bash
+$ java -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar='{ "inspectit": { "service-name": "My Custom Service" }}' -jar my-java-program.jar
+```
+
+### Java System Properties
+
+You can pass any configuration property as the Java System property to the Java command that you use to start your Java application.
+Using this approach you can change the `inspectit.service-name` property as follows:
+
+```bash
+$ java -Dinspectit.service-name="My Custom Service" -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar -jar my-java-program.jar
+```
+
+### OS Environment Variables
+
+Similar to the Java System properties, inspectIT Ocelot will also consider all the available operating system environment variables.
+Due to the relaxed bindings, you can use upper case format, which is recommended when using system environment variables.
+
+```bash
+$ INSPECTIT_SERVICE_NAME="My Custom Service" java -javaagent:/path/to/inspectit-ocelot-agent-2.6.2.jar -jar my-java-program.jar
+```
+
+## Relaxed Bindings
+
+Note that due to the Spring-powered configuration approach, the inspectIT Ocelot agent uses Spring support for relaxed bindings.
+This means that a property can be specified in different formats depending on the property source.
+As suggested by Spring, the allowed formats are:
+
+| Property | Note |
+| --- | --- |
+| `inspectit.service-name` | Kebab-case, which is recommended for use in `.properties` and `.yml` files. |
+| `inspectit.serviceName` | Standard camelCase syntax. |
+| `inspectit.service_name` | Underscore notation (snake_case), which is an alternative format for use in `.properties` and `.yml` files. |
+| `INSPECTIT_SERVICE_NAME` | UPPER_CASE format, which is recommended when using system environment variables. |
+
+The formats should be used in the following way, based on the type of property source:
+
+| Property Source | Format |
+| --- | --- |
+| System properties | Camel case, kebab case, or underscore notation. |
+| Environment Variables | Upper case format with the underscore as the delimiter. |
+| Property files (`.properties`) | Camel case, kebab case, or underscore notation. |
+| YAML files (`.yaml`, `.yml`) | Camel case, kebab case, or underscore notation. |
+
+## Environment Information
+
+Each agent stores the following information about its runtime environment: 
+
+| Property | Note |
+| --- | --- |
+| `inspectit.env.agent-dir` | Resolves to the path where the agent-jar is stored. |
+| `inspectit.env.hostname` | The hostname where the agent is running. |
+| `inspectit.env.pid` | The process id of the JVM process. |
+
+They are used to define the default behavior when writing the configuration persistence file and will be sent
+as attributes to the configuration server when fetching the configuration.
+
+You can reference these properties within the configuration using e.g. `${inspectit.env.agent-dir}` 
+as shown in the default configuration for 
+[HTTP-based configuration](configuration/external-configuration-sources.md#http-based-configuration).
+Referencing every other property follows the same schema.