# Quick Start: Export Your First Metrics

## Overview

`LMC Exporter` is a C++ exporter that reads LSEG/LMC shared-memory managed objects and renders app-specific metrics in Prometheus text format.

This quick start shows how to:

-   Use the installed tar archive executable.
-   Export your first metrics in snapshot mode.
-   Run the HTTP metrics endpoint for Prometheus-style scrapes.

The examples use the built-in `ads` app mapping and the example shared-memory server key `82`. Replace those values with the app and server key used by your LMC environment.

NoteScope

This article covers first-run usage only: installation, minimum configuration, snapshot mode, and HTTP metrics mode. It does not cover custom metric mapping generation, filter-group design, or contributor workflows.

## Prerequisites

Before you start, make sure you have:

<table><caption class="sr-only">Prerequisites</caption><thead><tr><th scope="col">Requirement</th><th scope="col">Notes</th></tr></thead><tbody><tr><td>Installed tar archive</td><td>Follow <a href="https://portal.cjcit.io/knowledge-base/lmc_exporter/0.19/getting-started/installation/">Installation</a>, including the active-install link. Examples use <code>el8</code>; use <code>el9</code> for the EL9 archive.</td></tr><tr><td>Runtime libraries</td><td>The matching platform libraries must be available on the host.</td></tr><tr><td>Licensing</td><td>The examples use a customer license file at <code>/opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic</code>. For online entitlement, use <a href="https://portal.cjcit.io/knowledge-base/lmc_exporter/0.19/configuration/gateway-licensing/">Gateway Licensing</a>.</td></tr><tr><td>Accessible LMC shared memory</td><td>Run as an account permitted to discover and read the configured shared-memory server key.</td></tr></tbody></table>

## How It Works

At startup, `lmc_exporter` creates a shared-memory server pool, discovers visible root handles, selects the best matching root, subscribes to child objects and variables under that root, and renders matched variables as Prometheus text.

The exporter can render metrics in two first-run modes:

Snapshot mode writes periodic Prometheus-style metric output to `stdout`. The interval is controlled by `--metrics-interval` or `metrics_interval_seconds`.

Use this mode when you want to inspect output directly from a terminal or capture snapshots with a process supervisor.

HTTP metrics mode starts a lightweight listener and serves the rendered Prometheus text on `/metrics` by default.

Use this mode when Prometheus or another scraper will collect metrics over HTTP.

NoteReadiness behavior

The exporter does not emit scrape output until the selected target subtree is fully subscribed and in sync. In HTTP mode, the endpoint can return `503` until the requested target is ready.

## Verify the Installation

Check the installed version:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 --version
```

The expected version is `v0.19.0`. Stop an existing exporter service before starting a foreground example on the same port.

## Configuration

You can configure the exporter with CLI flags or a TOML file. For quick-start usage, CLI flags are the fastest option.

### Required first-run values

<table><caption class="sr-only">Required first-run values</caption><thead><tr><th scope="col">Setting</th><th scope="col">CLI flag</th><th scope="col">TOML key</th><th scope="col">Description</th></tr></thead><tbody><tr><td>App mapping</td><td><code>--app</code></td><td><code>app</code></td><td>Selects the metric mapping set. Built-in app values include <code>ads</code>, <code>adh</code>, <code>ats</code>, <code>rtc</code>, and <code>rrcp_trans</code>.</td></tr><tr><td>Server key</td><td><code>--server-key</code></td><td><code>server_keys</code></td><td>Shared-memory server key used to discover the target root. Repeat the CLI flag for multiple keys.</td></tr><tr><td>License file</td><td><code>--license-file</code></td><td><code>license_file</code></td><td>Path to the customer license JSON file required in local-file mode.</td></tr></tbody></table>

### Optional first-run values

<table><caption class="sr-only">Optional first-run values</caption><thead><tr><th scope="col">Setting</th><th scope="col">CLI flag</th><th scope="col">TOML key</th><th scope="col">Description</th></tr></thead><tbody><tr><td>Instance hint</td><td><code>--instance</code></td><td><code>instance</code></td><td>Optional root-selection hint. Use a full root ID or a bare instance number when roots follow <code>hostname.instance_no.application</code> naming.</td></tr><tr><td>Snapshot interval</td><td><code>--metrics-interval</code></td><td><code>metrics_interval_seconds</code></td><td>Number of seconds between <code>stdout</code> snapshots.</td></tr><tr><td>Debug logging</td><td><code>--debug</code></td><td><code>debug</code></td><td>Enables verbose sync, update, and lookup diagnostics.</td></tr><tr><td>HTTP listener</td><td><code>--enable-metrics-http</code></td><td><code>metrics_http_enabled</code></td><td>Enables HTTP metrics mode.</td></tr><tr><td>HTTP bind address</td><td><code>--metrics-bind-address</code></td><td><code>metrics_bind_address</code></td><td>IPv4 bind address, such as <code>127.0.0.1</code> or <code>0.0.0.0</code>.</td></tr><tr><td>HTTP port</td><td><code>--metrics-port</code></td><td><code>metrics_port</code></td><td>HTTP listener port.</td></tr><tr><td>HTTP path</td><td><code>--metrics-path</code></td><td><code>metrics_path</code></td><td>Scrape path, usually <code>/metrics</code>.</td></tr></tbody></table>

NoteConfiguration precedence

When you use `--config`, TOML values are loaded first. CLI flags override TOML values afterward.

### Optional TOML quick-start file

Create `./lmcExporterConfig.toml` with the example below, or edit the installed configuration at `/opt/particle_horizon/local_config/lmc_exporter/lmc_exporter.toml`.

For a minimal single-target HTTP quick start, use:

```
context_id = "shmApp"
pool_name = "pool"

app = "ads"
server_keys = ["82"]

metrics_interval_seconds = 10
metrics_http_enabled = true
metrics_bind_address = "127.0.0.1"
metrics_port = 9464
metrics_path = "/metrics"

license_file = "/opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic"
```

Run with the config file:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 --config ./lmcExporterConfig.toml
```

## Usage

### Quickstart: Export Your First Metrics

Use a known server key and app mapping. This example uses app `ads`, server key `82`, and a license file at `/opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic`:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic
```

By default, when HTTP mode is not enabled, the exporter writes Prometheus-style snapshots to `stdout`.

To make root discovery easier to diagnose during a first run, add `--debug`:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic \
  --debug
```

If more than one visible root can match the server key, provide an instance hint:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --instance 1 \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic
```

The `--instance` value can be either the full root ID or the bare `instance_no` segment when roots use `hostname.instance_no.application` naming.

## Running in Snapshot Mode

Snapshot mode is the default mode when the HTTP listener is disabled.

Run a snapshot exporter with a 10-second interval:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --metrics-interval 10 \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic
```

The exporter writes Prometheus-style metric snapshots to `stdout`. Lookup and event diagnostics are written to `stderr`.

### Snapshot mode behavior

-   The exporter discovers the root for the configured server key.
-   It subscribes to the selected subtree.
-   It waits until the tracked subtree is fully subscribed and in sync.
-   It periodically writes rendered metrics to `stdout`.

NoteSnapshot output and readiness

If no metrics appear immediately, the exporter may still be waiting for the tracked subtree to synchronize. Use `--debug` to inspect root discovery, subscription, and sync diagnostics.

## Running in HTTP Metrics Mode

HTTP metrics mode serves the same rendered Prometheus output over an HTTP endpoint.

Start the exporter on port `9464`:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --enable-metrics-http \
  --metrics-bind-address 127.0.0.1 \
  --metrics-port 9464 \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic
```

Scrape metrics from another shell:

```
curl "http://127.0.0.1:9464/metrics?server_key=82"
```

When the HTTP listener is enabled, periodic Prometheus snapshots are no longer written to `stdout`.

### Route by resolved instance

After discovery, you can route by app and resolved instance:

```
curl "http://127.0.0.1:9464/metrics?app=ads&instance=phoads01.1.ads"
```

If more than one target shares the same `app` and `instance`, include `server_key` as well:

```
curl "http://127.0.0.1:9464/metrics?app=ads&instance=phoads01.1.ads&server_key=82"
```

### Use a custom metrics path

Set a custom HTTP path with `--metrics-path`:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --enable-metrics-http \
  --metrics-port 9464 \
  --metrics-path /metrics \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic
```

Scrape the configured path:

```
curl "http://127.0.0.1:9464/metrics?server_key=82"
```

## Examples

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --metrics-interval 10 \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic
```

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 \
  --server-key 82 \
  --app ads \
  --enable-metrics-http \
  --metrics-bind-address 127.0.0.1 \
  --metrics-port 9464 \
  --license-file /opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic
```

```
curl "http://127.0.0.1:9464/metrics?server_key=82"
```

```
context_id = "shmApp"
pool_name = "pool"

app = "ads"
server_keys = ["82"]

metrics_interval_seconds = 10
metrics_http_enabled = true
metrics_bind_address = "127.0.0.1"
metrics_port = 9464
metrics_path = "/metrics"

license_file = "/opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic"
```

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 --config ./lmcExporterConfig.toml
```