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 | 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.
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. The length of a session-ID is restricted to a minimum of 64 characters and a maximum of 512 characters.
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.
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 | Cookie | 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.
Client Example
This example should demonstrate, how you can call the REST-API in your frontend application.
// 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.withCredentials = true; // Send cookies with the request
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.withCredentials = true; // Send cookies with the request
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:
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. Per default, the Cookie-header 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.
security:
- session_id: []
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 Origin header
'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.
security:
- session_id: []
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 Origin header
'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
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-Credentials:
schema:
type: boolean
'403':
description: Forbidden - Missing required headers
components:
securitySchemes:
session_id:
type: apiKey
description: |
ID of the current session. The session-ID-header-name can be configured in the InspectIT configuration-server.
Per default, the Cookie-Header will be used as the session-ID-header.
The length of the session-id is restricted to a minimum of 16 characters and a maximum of 512 characters.
name: Cookie
in: header
externalDocs:
description: More information about the Exporter API
url: https://inspectit.github.io/inspectit-ocelot/docs/tags/tags-exporters