Skip to content
Platform > Operations > OpenTelemetry

Sending metrics to a collector

This guide turns on OpenTelemetry export for a 3forge Enterprise installation and confirms that metrics reach your collector.

Export is controlled entirely by properties in config/local.properties, which the server reads at startup. Every step is either an edit to that file or a restart; there is no UI, console command, or AMI SQL for this feature.

Prerequisites

  • A 3forge Enterprise installation you can stop and start. See Starting and stopping.
  • An OpenTelemetry collector, or another OTLP/HTTP receiver, listening for OTLP over HTTP. Its default port is 4318.

Steps

  1. Open config/local.properties in the installation directory.

  2. Add this line:

    1
    ami.log.stats.otel.enabled=true

    Put it on its own line. A # starts a comment only at the beginning of a line, so a comment after a value becomes part of the value. On a numeric setting such as ami.log.stats.otel.max.retries, that turns export off for as long as the server runs.

  3. If the collector is not on the same machine at port 4318, add its base URL. Include the scheme, e.g: http://, and leave off /v1/metrics, which is added for you:

    1
    ami.log.stats.otel.endpoint=http://collector.example.com:4318

    Without the scheme, nothing is sent and no warning names the export. See Troubleshooting.

  4. Restart the server. Settings are read only at startup.

  5. Confirm the settings were loaded. The startup log, which starts afresh at every restart, lists the export settings the server is using. Run from the installation directory:

    1
    Select-String -Path log\AmiCore.log -Pattern '^\|\s+ami\.log\.stats\.otel\.' | ForEach-Object { $_.Line }

    1
    grep -E '^\|[[:space:]]+ami\.log\.stats\.otel\.' log/AmiCore.log

    Each value is shown exactly as it was read, including anything after it on the same line. With only ami.log.stats.otel.enabled=true set, the output is:

    1
2
3
4
5
    |                         ami.log.stats.otel.enabled=true
|                         ami.log.stats.otel.endpoint=http://localhost:4318
|                         ami.log.stats.otel.headers=
|                         ami.log.stats.otel.max.retries=5
|                         ami.log.stats.otel.request.timeout=10000

    Setting ami.log.stats.otel.service.name adds a sixth line, and the order of the lines varies. If only ami.log.stats.otel.enabled=false appears, the property was not read: check its spelling, which begins ami.log.stats.otel, not ami.amilog.stats.

  6. Confirm the data arrived at the collector. The first request arrives about 2 seconds after startup, then one request of metrics and one of log records every 15 seconds.

Result

The collector receives metrics named after the statistic they come from, such as Process.freeMem, Process.gcCount, and AmiCenterEvents.logins, with service.name set to AmiCore. The first request carries only the 10 Process.* metrics, and the second carries the most, 48 on a new installation. After that, each request carries only the statistics recorded since the one before, so some metrics arrive every 15 seconds and others once a minute or once per start; see How often each metric arrives.

To see what each metric means, see the metrics reference. To name the server, send to a collector that needs credentials, or change the timeout, see Configuration.