> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corelayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Metrics: Track Custom Pipeline Metrics

> Instrument any pipeline or application with the Corelayer SDK to push custom metrics, build baselines per partition, and detect anomalies in your own data.

## Overview

API metrics let you track custom data quality metrics from any codebase — ETL pipelines, batch jobs, microservices, or applications. You push observations with the Corelayer SDK; Corelayer builds a statistical baseline for each partition and raises findings when values fall outside the expected band.

## Prerequisites

* A connected GitHub or GitLab integration, with the repository you want to track synced to Corelayer
* Node.js 18 or later (the SDK uses the built-in `fetch`)

## Onboarding

### 1. Create an API key

1. In your Corelayer dashboard, go to **Settings > API Keys**
2. Click **Create Key**
3. Give it a name (for example `Production ETL`) and choose an expiration — never, 30, 60, or 90 days, or 1 year
4. Click **Create**
5. Copy the key immediately. It starts with `cl_live_` and is shown only once.

### 2. Set the environment variables

```bash theme={null}
export CORELAYER_API_KEY="cl_live_your_api_key_here"
export CORELAYER_BASE_URL="https://api.corelayer.com"
```

For production, set both in your environment configuration — `.env`, Docker secrets, CI/CD variables, or your cloud provider's secret manager.

### 3. Install the SDK

```bash theme={null}
npm install @corelayer-ai/sdk
```

### 4. Create the rule in the dashboard

1. Go to **Anomaly Rules** and click **Add**
2. Under **Codebases**, pick the repository
3. Click **Add API metric**
4. Fill in the configuration:
   * **Anomaly rule name** — a human-readable label, for example `Daily Order Volume`
   * **Expected cadence** — how often your application sends this metric (hourly, daily, weekly, monthly)
   * **Detector** — which statistical method scores the metric. `Baseline` is the default; see [Detectors](/anomalies/overview#detectors).
   * **Minimum data points** — how many observations to learn before flagging. Leave blank for the detector default.
5. Copy the **Metric ID** and the **SDK snippet** from the page
6. Click **Save**

<Tip>
  The page also offers a **Copy agent instructions** button, which puts a short Markdown brief on your clipboard — paste it into a coding agent to have it wire up the SDK for you.
</Tip>

### 5. Instrument your code

```javascript theme={null}
import { CorelayerClient } from '@corelayer-ai/sdk';

const client = new CorelayerClient({
  apiKey: process.env.CORELAYER_API_KEY,
  baseUrl: process.env.CORELAYER_BASE_URL,
});

client.trackMetric({
  metricId: "<your-metric-id>",
  partitions: [
    { keys: { "region": "us-east-1", "table": "orders" }, value: 1523 },
  ],
  timestamp: "2025-01-15T00:00:00Z",
});

// Call at process exit to flush remaining metrics
await client.shutdown();
```

**Parameters**:

* `metricId` — the UUID from step 4. Identifies which rule this data belongs to.
* `partitions` — an array of partition entries. Each has `keys` (an object of key/value pairs identifying the partition) and `value` (the numeric measurement). Each unique key combination gets its own baseline.
* `timestamp` — an ISO 8601 timestamp. Optional; defaults to now. Pass it explicitly for batch jobs so reruns bucket correctly.

<Warning>
  Always set `CORELAYER_BASE_URL`. If you omit `baseUrl`, the SDK falls back to a built-in default that is not the production API.
</Warning>

### 6. Deploy and monitor

Once your code is deployed and sending data, Corelayer will:

1. Collect observations to build a baseline for each partition — the rule shows **Collecting**
2. Switch to active monitoring once a partition has enough data — it shows **Ready**
3. Flag observations that fall outside the expected band

## Client Configuration

`trackMetric` queues locally and flushes in the background, so it does not block your pipeline.

| Option            | Default | Description                                                                                      |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `apiKey`          | —       | Required. Your `cl_live_` API key.                                                               |
| `baseUrl`         | —       | Set to `https://api.corelayer.com`.                                                              |
| `flushIntervalMs` | `5000`  | How often the queue is flushed.                                                                  |
| `maxBatchSize`    | `100`   | Batch size. Reaching it triggers an immediate flush.                                             |
| `maxQueueSize`    | `1000`  | Queue cap before entries are dropped.                                                            |
| `maxRetries`      | `4`     | Retries per batch on `429` and `5xx`, with backoff of 500ms, 1s, 2s, 4s, honoring `Retry-After`. |
| `timeoutMs`       | `5000`  | Per-request timeout.                                                                             |
| `debug`           | `false` | Log delivery failures to the console.                                                            |

<Note>
  `flush()` and `shutdown()` do not throw on delivery failure. Set `debug: true` while integrating so failed batches are visible.
</Note>

## Environment Variables Reference

| Variable             | Required | Description                                                                  |
| -------------------- | -------- | ---------------------------------------------------------------------------- |
| `CORELAYER_API_KEY`  | Yes      | API key for authenticating SDK calls. Create one at **Settings > API Keys**. |
| `CORELAYER_BASE_URL` | Yes      | The Corelayer API endpoint. Set to `https://api.corelayer.com`.              |

## Viewing Metrics

### Rule listing

From **Anomaly Rules**, the **API** section groups codebases by account and shows how many rules each has. Open a codebase to see its rules. Each row shows the rule name, its cadence, and whether the baseline is **Collecting** or **Ready**.

### Rule detail page

Open a rule to see the **Overview** tab:

* **Stat cards** — partitions observed, baselines ready, and anomalies detected in the selected range
* **Time range selector** — presets scaled to the rule's cadence (an hourly rule offers 1d/3d/7d, a daily rule 7d/14d/30d, a weekly rule 90d/6mo/1y, a monthly rule 6mo/1y/2y)
* **Partition Inspector** — a searchable, paginated list of partitions showing mean, min, and max with a sparkline. Select one to load its chart, baseline state, and findings.
* **Anomaly findings** — findings for the selected partition

Click **Configure** to open the **Settings** tab and edit the rule.

### Anomaly findings

Each finding shows:

* **Severity** — Critical, High, Medium, Low, or Info
* **Detector** — which method produced it
* **Observed vs. Expected** — the actual value against what the baseline predicted
* **Expected range** — the bounds that were breached
* **Timestamp** — when it was detected
* **Linked issue** — if the finding opened a Corelayer issue, a link to it and whether it is still open

## Tips

* **Use descriptive partition keys** — keys like `region`, `pipeline`, or `table_name` make findings easier to diagnose.
* **Set explicit timestamps for batch jobs** — this keeps data bucketed correctly, even during reruns.
* **Call `client.shutdown()`** — always flush before your process exits, or the last batch is lost.
* **One rule per logical measurement** — keep `Order Volume` and `Payment Processing Time` as separate rules rather than mixing them.
* **Do not over-partition** — every unique key combination needs enough observations of its own to train. Too many partitions means none of them reach **Ready**.

## Managing Rules

### Changing the detector or cadence

Open the rule and switch to **Settings**. Changing the **detector** retrains from stored history automatically. Changing the **expected cadence** re-buckets observations, so Corelayer asks whether to keep the existing baseline or reset it — keeping it can produce noisy findings until enough new observations arrive.

**Reset Baseline** discards learned state and rebuilds from scratch on the next run.

### Deleting rules

On a codebase's rule list, select one or more rules with the checkboxes and click **Delete**. This permanently removes the rules and their history.

### Rotating API keys

1. Go to **Settings > API Keys**
2. Click the rotate icon next to the key
3. Copy the new key and update `CORELAYER_API_KEY`
4. The old key is revoked immediately

Need help? [Contact support](mailto:support@corelayer.com) for assistance with API metrics.


## Related topics

- [Anomaly Detection for Data Pipelines](/anomalies/overview.md)
- [Corelayer Changelog: April 2026 Release](/changelog/april-2026.md)
- [Corelayer Changelog: February 2026, v1.2.0](/changelog/february-2026.md)