{"id":19721878,"url":"https://github.com/inspectit/inspectit-ocelot-eum-server","last_synced_at":"2025-06-15T17:03:21.332Z","repository":{"id":38309185,"uuid":"490223102","full_name":"inspectIT/inspectit-ocelot-eum-server","owner":"inspectIT","description":"Server to receive EUM data and export them to Observability backends","archived":false,"fork":false,"pushed_at":"2025-03-28T14:46:48.000Z","size":2326,"stargazers_count":11,"open_issues_count":3,"forks_count":8,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-05T19:51:12.727Z","etag":null,"topics":["apm","end-user-monitoring","monitoring","observability","openapm","opentelemetry"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inspectIT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-09T09:47:17.000Z","updated_at":"2025-03-27T10:34:31.000Z","dependencies_parsed_at":"2023-02-14T19:30:54.500Z","dependency_job_id":"dfc3edc2-4397-4c5b-9693-025d2efea38c","html_url":"https://github.com/inspectIT/inspectit-ocelot-eum-server","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspectIT%2Finspectit-ocelot-eum-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspectIT%2Finspectit-ocelot-eum-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspectIT%2Finspectit-ocelot-eum-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspectIT%2Finspectit-ocelot-eum-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inspectIT","download_url":"https://codeload.github.com/inspectIT/inspectit-ocelot-eum-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251585862,"owners_count":21613286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apm","end-user-monitoring","monitoring","observability","openapm","opentelemetry"],"created_at":"2024-11-11T23:15:49.681Z","updated_at":"2025-04-29T21:31:29.904Z","avatar_url":"https://github.com/inspectIT.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# inspectit-ocelot-eum-server\n\n[![EUM Server Tests](https://github.com/inspectIT/inspectit-ocelot-eum-server/actions/workflows/eumserver_test.yml/badge.svg?branch=main)](https://github.com/inspectIT/inspectit-ocelot-eum-server/actions/workflows/eumserver_test.yml)\n\nThis server provides Enduser Monitoring data by using the [OpenCensus](https://github.com/census-instrumentation/opencensus-java) toolkit.\n\n## Metrics\nThe inspectit-ocelot server offers a backend for Javascript monitoring with [Boomerang](https://developer.akamai.com/tools/boomerang/docs/index.html).\nBoomerang is a Javascript metrics agent, which is able to capture arbitrary customizable metrics. \nBy injecting the following snipped in your webpage, all measured metrics are sent to the inspectit-ocelot-eum-server:\n```javascript\n\u003cscript src=\"boomerang-1.0.0.min.js\"\u003e\u003c/script\u003e\n \u003cscript src=\"plugins/rt.js\"\u003e\u003c/script\u003e\n \u003c!-- any other plugins you want to include --\u003e\n \u003cscript\u003e\n   BOOMR.init({\n     beacon_url: \"http://[inspectit-eum-server-url]:8080/beacon/\"\n   });\n \u003c/script\u003e\n```\nBoomerang recommends to use an advanced injection, where the boomerang agent is loaded in an asynchronous way. \nFor further information, please visit the [Boomerang documentation](https://developer.akamai.com/tools/boomerang/docs/index.html).\n\nIf enabled, the server exposes the metrics by using the [Prometheus exporter](https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/stats/prometheus).\nA tutorial on how to install Prometheus can be found [here](https://opencensus.io/codelabs/prometheus/#0).\n\n## Server Setup\nBefore starting the server, please build the server by cloning the repository and executing the following command or download the [latest release](https://github.com/inspectIT/inspectit-ocelot/releases).\n```bash\n$ ./gradlew build\n```\nStart the server with the following command:\n```bash\n$ java -jar inspectit-ocelot-eum-{version}.jar\n```\nBy default, the server is starting with the port `8080`. \nYou can simply configure the port by using the Java property `-Dserver.port=[port]`:\n```bash\n$ java -Dserver.port=[port] -jar inspectit-ocelot-eum-0.0.1-SNAPSHOT.jar\n```\nOur server is delivered with a default configuration \nsupporting the metrics `t_page`, `t_done`, `rt.tstart`, `rt.nstart` and `rt.end` of the Boomerang plugin [RT](https://developer.akamai.com/tools/boomerang/docs/BOOMR.plugins.RT.html).\nIn order to provide a custom configuration, please set the Java property `-Dspring.config.location=file:[path-to-config]`:\n\n```bash\n$ java -Dserver.port=[port] -Dspring.config.location=file:[path-to-config] -jar inspectit-ocelot-eum-0.0.1-SNAPSHOT.jar\n```\n\n## Configuration\nThe configuration file defines the mapping between the concrete Boomerang metric and a OpenCensus metric, as the following sample configuration file shows:\n```yaml\ninspectit-eum-server:\n  definitions:\n    page_ready_time:\n      measure-type: LONG\n      beacon-field: t_page\n      unit: ms\n      views:\n        '[page_ready_time/SUM]': {aggregation: SUM}\n        '[page_ready_time/COUNT]': {aggregation: COUNT}\n    load_time:\n      measure-type: LONG\n      beacon-field: t_done\n      unit: ms\n      views:\n        '[load_time/SUM]': {aggregation: SUM}\n        '[load_time/COUNT]': {aggregation: COUNT}\n\n    start_timestamp:\n      measure-type: LONG\n      beacon-field: rt.tstart\n      unit: ms\n\n    navigation_start_timestamp:\n      measure-type: LONG\n      beacon-field: rt.nstart\n      unit: ms\n\n    end_timestamp:\n      measure-type: LONG\n      beacon-field: rt.end\n      unit: ms\n      views:\n        end_timestamp:\n          aggregation: LAST_VALUE\n          tags: {APPLICATION : true}\n  tags:\n    extra:\n      APPLICATION: my-application\n    beacon:\n      URL: u\n      OS: ua.plt\n    global:\n      - URL\n      - OS\n      - COUNTRY_CODE\n  exporters:\n    metrics:\n      prometheus:\n        enabled: ENABLED\n        host: localhost\n        port: 8888\n    tracing:\n      otlp:\n        enabled: ENABLED\n        protocol: grpc\n        endpoint: localhost:4317\n\n  security:\n    enabled: false\n    authorization-header: Authorization\n    permitted-urls:\n      - \"/actuator/health\"\n      - \"/boomerang/**\"\n    auth-provider:\n      simple:\n        enabled: false\n        watch: true\n        frequency: 60s\n        token-directory: \"\" # Empty by default to force users to provide one\n        default-file-name: \"default-token-file.yaml\"\n```\n##### Metrics Definition\nA metric is defined through the following attributes:\n* `name`: Defines the name of the metric. The name of the exposed view will have the used aggregation as suffix.\n* `measure-type`: Can be either `LONG` or `DOUBLE`.\n* `beacon-field`: The beacon key name, which is used as source of metric.\n* `description`: Optional. Defines an additional description of the exposed metric.\n* `unit`: The unit of the metric.\n* `tag-keys`: Optional. Defines a list of tag keys, which are exposed with the current metric.\n* `views`: A list of the views, which should be exposed. The aggregation can be either `SUM`, `COUNT`, `LAST_VALUE` or `HISTORGRAM`. For using `HISTOGRAM`, the field `bucket-boundaries` is mandatory.\n* `bucket-boundaries`: Used for the `HISTOGRAM` aggregation, defines the bucket boundaries as list of Doubles.\n\n##### Tags Definition\nWe distinguish between to different types of tags:\n* `extra`- tags: Extra tags define tags, which are manually set in the configuration. The field `extra` holds a list of key-value mappings.\n* `beacon`- tags: Beacon tags define tags, whose tag value is resolved by a beacon entry. The defined value of the `beacon` map will be resolved by using the provided beacon.\nIn order to provide selected tags to each measurement by default, tags can be defined as global. `global` holds a list of already defined tags, which will be then exposed for each measurement.\n\n##### Automated Geolocation Detection\nBy using the tag `COUNTRY_CODE`, the geolocation of the requester is resolved by using the requester IP and the [GeoLite2 database](https://www.maxmind.com). If the IP cannot be resolved, the tag value will be empty.\n\n##### Metrics Exporters\n\nThe inspectIT Ocelot EUM Server currently supports the following metrics exporters:\n\n|Exporter |Supports run-time updates| Push / Pull |Enabled by default|\n|---|---|---|---|\n|[Prometheus Exporter](#prometheus-exporter)|Yes|Pull|No|\n|[InfluxDB Exporter](#influxdb-exporter)|Yes|Push|No|\n|[OTLP Exporter (Metrics)](#otlp-exporter-metrics) [[Homepage](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp/metrics)]|Yes|Push|No|\n\n###### Prometheus Exporter\nIf `enabled` is set to `ENABLED`, the exporter exposes the metrics under \n```bash\nhttp://[host]:[port]/metrics\n```\n\nPrometheus exporter exposes the metrics in Prometheus format.\nWhen enabled, the EUM  starts a Prometheus HTTP server in parallel with your application.\nThe server is by default started on the port `8888` and metrics can then be accessed by visiting http://localhost:8888/metrics.\n\nThe following properties are nested properties below the `inspectit-eum-server.exporters.metrics.prometheus` property:\n\n|Property | Default    | Description\n|---|------------|---|\n|`.enabled`| `DISABLED` |If `ENABLED` or `IF_CONFIGURED`, the inspectIT Ocelot agent will try to start the Prometheus metrics exporter and Prometheus HTTP server.\n|`.host`| `0.0.0.0`  |The hostname or network address to which the Prometheus HTTP server should bind.\n|`.port`| `8888`     |The port the Prometheus HTTP server should use.\n\n\n###### InfluxDB Exporter\nIf enabled, metrics are pushed at a specified interval directly to a given InfluxDB v1.x instance.\nTo enable the InfluxDB Exporters, it is only required to specify the `endpoint`.\n\nThe InfluxDB exporter provides a special handling for counter and sum metrics which is enabled by default and can be disabled using the `counters-as-differences` option.\nUsually, the absolute value of such counters is irrelevant when querying the data, instead you want to have the increase of it over a certain period of time.\nWith the `counters-as-differences` option enabled, counters are preprocessed before being exported.\n\nInstead of writing the absolute value of each counter into the InfluxDB, only the increase since the last export will be written.\nIn addition, no value will be exported, if the counter has not changed since the last export.\nThis can greatly reduce the amount of data written into the InfluxDB, especially if the metrics are quite constant and won't change much.\n\nThe following properties are nested properties below the `inspectit.exporters.metrics.influx` property:\n\n\n|Property | Default                                 | Description|\n|---|-----------------------------------------|---|\n|`.enabled`| `IF_CONFIGURED`                         |If `ENABLED` or `IF_CONFIGURED`, the agent will try to start the Influx exporter. If the url is not set, it will log a warning if set to `ENABLED` but fail silently if set to `IF_CONFIGURED`.|\n|`.endpoint`| `null`                                  |The HTTP endpoint of the InfluxDB, e.g. `http://localhost:8086`.|\n|`.user`| `null`                                  | The user to use for connecting to the InfluxDB, can not be empty.|\n|`.password`| `null`                                  |The password to use for connecting to the InfluxDB, can be not be empty.|\n|`.database`| `inspectit`                             | The InfluxDB database to which the metrics are pushed.|\n|`.retention-policy`| `autogen`                               | The retention policy of the database to use for writing metrics.|\n|`.create-database`| `true`                                  | If enabled, the database defined by the `database` property is automatically created on startup with an `autogen` retention policy if it does not exist yet.|\n|`.export-interval`| refers to `inspectit.metrics.frequency` |Defines how often metrics are pushed to the InfluxDB.|\n|\u003cnobr\u003e`.counters-as-differences`\u003c/nobr\u003e| `true`                                  |Defines whether counters are exported using their absolute value or as the increase between exports|\n|`buffer-size`| `40`                                    | In case the InfluxDB is not reachable, failed writes will be buffered and written on the next export. This value defines the maximum number of batches to buffer.|\n\n###### OTLP Exporter (Metrics)\n\n\nThe OpenTelemetry Protocol (OTLP) exporters export the metrics to the desired endpoint at a specified interval.\nTo enable the OTLP exporters, it is only required to specify the `endpoint`.\n\nThe following properties are nested properties below the `inspectit-eum-server.exporters.metrics.otlp` property:\n\n| Property                 | Default         | Description                                                                                                                                                                                                                  |\n|--------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `.enabled`               | `IF_CONFIGURED` | If `ENABLED` or `IF_CONFIGURED`, the inspectIT Ocelot agent will try to start the OTLP gRPC metrics exporter.                                                                                                                |\n| `.endpoint`              | `null`          | Target to which the exporter is going to send metrics, e.g. `http://localhost:4317`                                                                                                                                          |\n| `.protocol`              | `null`          | The transport protocol, see [OTEL documentation](https://opentelemetry.io/docs/reference/specification/protocol/exporter/). Supported protocols are `grpc` and `http/protobuf`.                                              |\n| `.preferred-temporality` | `CUMULATIVE`    | The preferred output aggregation temporality, see [OTEL documentation](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md). Supported values are `CUMULATIVE` and `DELTA`.| \n| `.headers`               | `null`          | Key-value pairs to be used as headers associated with gRPC or HTTP requests, see [OTEL documentation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md).|\n| `.compression`           | `NONE`          | The compression method, see [OTEL documentation](https://opentelemetry.io/docs/reference/specification/protocol/exporter/). Supported compression methods are `gzip` and `none`.                                   |\n| `.timeout`               | `10s`           | Maximum time the OTLP exporter will wait for each batch export, see [OTEL documentation](https://opentelemetry.io/docs/reference/specification/protocol/exporter/).                           |\n\n##### Trace Exporters\n\nTracing exporters are responsible for passing the recorded tracing data to a corresponding storage.\nThe inspectIT Ocelot EUM Server currently supports the following trace exporters:\n\n* [OTLP (Traces)](#otlp-exporter-traces) [[Homepage](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp/trace)]\n\n###### General Trace Exporter Settings\n\nThese settings apply to all trace exporters and can set below the `inspectit-eum-server.exporters.tracing` property.\n\n| Property        | Default                     | Description                                                                                                                                                               |\n|-----------------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `.service-name` | `${inspectit.service-name}` | The value of this property will be used to identify the service a trace came from. Please note that changes of this property only take effect after restarting the agent. |\n\n###### OTLP Exporter (Traces)\n\nThe OpenTelemetry Protocol (OTLP) exporters export the Traces in OTLP to the desired endpoint at a specified interval.\nBy default, the OTLP exporters are enabled but the URL `endpoint` needed for the exporter to actually start is set to `null`.\n\nThe following properties are nested properties below the `inspectit.exporters.tracing.otlp` property:\n\n| Property       | Default         | Description                                                                                                                                                                                                        |\n|----------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `.enabled`     | `IF_CONFIGURED` | If `ENABLED` or `IF_CONFIGURED`, the inspectIT Ocelot agent will try to start the OTLP gRPC trace exporter.                                                                                                        |\n| `.endpoint`    | `null`          | Target to which the exporter is going to send traces, e.g. `http://localhost:4317`                                                                                                                                 |\n| `.protocol`    | `grpc`          | The transport protocol, see [OTEL documentation](https://opentelemetry.io/docs/reference/specification/protocol/exporter/). Supported protocols are `grpc` and `http/protobuf`.                                    |\n| `.headers`     | `null`          | Key-value pairs to be used as headers associated with gRPC or HTTP requests, see [OTEL documentation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md). |\n| `.compression` | `NONE`          | The compression method, see [OTEL documentation](https://opentelemetry.io/docs/reference/specification/protocol/exporter/). Supported compression methods are `gzip` and `none`.                                   |\n| `.timeout`     | `10s`           | Maximum time the OTLP exporter will wait for each batch export, see [OTEL documentation](https://opentelemetry.io/docs/reference/specification/protocol/exporter/).                           |\n\n\n###### Jaeger Exporter (removed)\n\nSince version 2.6.2 the InspectIT EUM-Server does no longer support the Jaeger exporter.\n\n##### Security\nCurrently, the EUM Server only supports a simple API token security concept. In future, additional authentication providers\nwill be supported.\nSecurity can be enabled by changing spring `application.yml`, using system properties or environment variables.\n\n```yaml\ninspectit-eum-server:\n  ....\n  security:\n    enabled: true\n    authorization-header: Authorization\n    permitted-urls:\n      - \"/actuator/health\"\n      - \"/boomerang/**\"\n    auth-provider:\n      # List of providers\n      ....\n```\n\n###### Simple Token Provider\nThe simple token provider can be enabled from config file...\n\n```yaml\ninspectit-eum-server:\n  ....\n  security:\n    ....\n    auth-provider:\n      simple:\n        # Enable/Disable Provider\n        enabled: true\n        # Flag indicates if the directory should be watched for changes and tokens reloaded\n        watch: true\n        # How often directory should be watched for changes\n        frequency: 60s\n        # The directory where token files are stored. Empty by default to force users to provide one\n        token-directory: \"\"\n        # The name of the initial token file\n        default-file-name: \"default-token-file.yaml\"\n```\nor via environment variables:\n```bash\nINSPECTIT_EUM_SERVER_SECURITY_AUTH_PROVIDER_SIMPLE_TOKEN_DIRECTORY=\u003cmy-directory\u003e\nINSPECTIT_EUM_SERVER_SECURITY_AUTH_PROVIDER_SIMPLE_ENABLED=TRUE;\nINSPECTIT_EUM_SERVER_SECURITY_ENABLED=TRUE\n```\n\nThe format for the token files is as follows:\n```yaml\n  # Identifies a token. E.g. you can document which application, person, organization, etc. knows about this token. It has no influence on security.\n- name: \"Name for first token\"\n  # The value of the token. If an HTTP-request contains this value (without opening and closing double quotes), access is allowed.\n  token: \"755f3e71-e43f-4715-bd26-b6e112fd30dd\"\n  # You may specify as many elements as you like\n- name: \"Name of other token\"\n  token: \"any token value you like\"\n```\n\n\n##### Build Docker Image Locally.\n\nIn order to build a docker image locally, the eum-server should be build locally and the resulting jar should be renamed\nto ```inspectit-ocelot-eum-server.jar``` and copied to the ./docker directory\n\n##### How to Release\nTo create a new release, you have to create a new git tag and push it on to GitHub. \nThis Tag is the new version number of the release. Afterwards the release build will be automatically triggered.\n\nImportant tasks to check first are `dependencyUpdates` and `dependencyUpdates[Major|Minor]` for newer (patch, minor, major)\nversions and `dependencyCheckAnalyze` for security issues in the used dependencies. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finspectit%2Finspectit-ocelot-eum-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finspectit%2Finspectit-ocelot-eum-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finspectit%2Finspectit-ocelot-eum-server/lists"}