# Coralogix

Forwards records to [Coralogix](https://coralogix.com) for observability, search, and analytics.

## Requirements

- A Coralogix account and access to the region your team is provisioned in (`us1`, `us2`, `us3`, `eu1`, `eu2`, `ap1`, `ap2`, or `ap3`).
- A [Send-Your-Data API key](https://coralogix.com/docs/send-your-data-api-key/) from your Coralogix account.

### Obtaining Coralogix credentials

1. **Identify your region.** The region determines which ingress hostname your data is sent to. Sign in to Coralogix and check the URL against the [Coralogix Endpoints](https://coralogix.com/docs/integrations/coralogix-endpoints/) reference.
2. **Create a Send-Your-Data API key.**
   - In Coralogix, open **Settings → API Keys**.
   - Click **Add Key**.
   - Select **Send Your Data Key** and give it a name (e.g. `Monad`).
   - Copy the key immediately — Coralogix only shows it once.

## Timestamp resolution

The optional **Timestamp Record Location** field controls how Monad chooses the `timestamp` on each record. It accepts either [JSONPath](https://goessner.net/articles/JsonPath/) (`$.event.time`) or native [gjson](https://github.com/tidwall/gjson) syntax (`event.time`).

| Situation | Behavior |
|-----------|----------|
| Field unset | Every record is stamped with the current time. |
| Path set, field missing on this record | The current time is used for that record. |
| Path set, field present and parseable | The parsed value is used (Unix milliseconds after normalization). |
| Path set, field present but not a parseable timestamp | The entire batch fails loudly and is retried. Mis-timestamped records in Coralogix are worse than a retry, so the connector prefers to error out. |

Supported timestamp shapes include RFC 3339 strings (`"2024-01-02T03:04:05Z"`), Unix seconds/milliseconds/microseconds/nanoseconds as numbers or strings, and other common formats parsed by Monad's shared time normalizer.

## Configuration

The following configuration defines the output parameters. Each field's specifications — type, requirements, and description — are detailed below.

### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| Region | one-of | Yes | Coralogix region. Determines the regional ingress hostname (e.g. `eu2` → `ingress.eu2.coralogix.com`). Valid options: `us1`, `us2`, `us3`, `eu1`, `eu2`, `ap1`, `ap2`, `ap3`. Default: `us1`. |
| Application Name | string | Yes | Stamped on every record as `applicationName`. Coralogix uses this to separate environments or tenants (e.g. `aikido`). |
| Subsystem Name | string | Yes | Stamped on every record as `subsystemName`. Coralogix uses this to separate components within an application (e.g. `prod`). |
| Timestamp Record Location | string | No | JSONPath or gjson path pointing at the timestamp field inside each incoming record (e.g. `$.timestamp`, `event.time`). If unset, Monad stamps the current time on every record. See [Timestamp resolution](#timestamp-resolution). |
| Communication | one-of | Yes | Transport used to reach Coralogix. Only `rest` (Send-Your-Data) is available today. |
| Batch Config | object | No | Controls when a batch is sent by limiting record count, total size, and elapsed time. |

### Communication — REST (Send-Your-Data)

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| Send-Your-Data API Key | secret | Yes | Coralogix Send-Your-Data API key. Sent as the `Authorization: Bearer <key>` header on every request. |

## Limitations

- **2 MB per request** — Coralogix rejects requests larger than 2 MB (~3,000 medium-sized logs). Monad defaults the batch data size to 1.5 MB to stay under this cap.
- **Static application / subsystem** — `applicationName` and `subsystemName` are per-pipeline. Per-record extraction is not currently supported.
- **REST only** — OTLP and TLS syslog transports are on the roadmap but not shipped in this connector. If you need OTLP today, use Monad's `otel` output with Coralogix's OTLP ingress and the `Authorization`, `CX-Application-Name`, `CX-Subsystem-Name` headers.
- **HTTP request timeout is 30 seconds.** Batches that don't complete within this window are treated as failures and retried.

## Troubleshooting

- **Connection refused / timeouts** — verify the **Region** matches the region on your Coralogix account. Sending to the wrong regional ingress will produce timeouts or `401`/`403` errors.
- **`401 Unauthorized` / `403 Forbidden`** — regenerate the Send-Your-Data API key and confirm it has the `SendData` permission. Keys are region-scoped; a key from a different Coralogix account or region will not work.
- **`413 Payload Too Large`** — reduce the batch data size in **Batch Config** so batches stay under the 2 MB request cap.
- **`429 Too Many Requests`** — Coralogix is rate-limiting the account. Lower the publish rate or contact Coralogix to raise your ingest quota.
- **Records show the wrong time** — set **Timestamp Record Location** to the field on your records that carries the event time. If the path evaluates to an unparseable value, the batch will fail with a clear error naming the field.
- **Records show up under the wrong app or subsystem in Coralogix** — check **Application Name** and **Subsystem Name**; both are stamped verbatim onto every record.