Connect Custom Data Sources — Consolidated Reference

Purpose: Single-document reference for vibe coding against the Eyer custom data source integration. Consolidates all 8 pages from the "Connect Custom Data Sources" section of the Eyer Knowledge Base. Last synced: 2026-04-03.

1. Overview (README FIRST)

Data can come from an open source agent, custom code, scripts, or instrumented existing code.

Two paths:

• Path A — Open source / custom agent (no format control): You need a mapping from your agent's JSON output to the Eyer internal format. Follow Section 1 below.

• Path B — Instrumented code (you control output format): Skip mapping. Format directly to the Eyer generic format. Follow Section 2 below.

Path A — Step by step

1. Get your metrics with names and timestamps in a flat JSON format. Less nesting = easier mapping.

2. Structure data with metrics/values in a fields section and metadata in a tags section. The fields section can repeat (e.g., one per database).

3. Create a mapping from your data to the Eyer internal format (see mapping examples below).

4. Validate the mapping via the Push API test endpoint.

5. Contact Eyer to enable your custom endpoint.

Example flat JSON (Telegraf output):

Path B — Step by step

1. Refer to the Eyer generic input format (Section 5 below).

2. Structure your output accordingly.

3. Contact Eyer to enable your custom endpoint.

2. Input Data Format Requirements

Core rules

1. Eyer ingests time series data: sequential data points with timestamps and one or more measured values.

2. All data must be in JSON format. Prefer flatter structures with limited nesting.

3. Timestamps must be in epoch (1745352000000) or ISO (2025-11-11T11:00:00Z) format.

4. Recommended resolution: 1-minute aggregates before sending. Eyer's minimum operating resolution is 1 minute.

5. If local aggregation is not feasible, send raw data. Eyer will aggregate automatically to per-minute.

6. If no aggregation function is specified, Eyer defaults to average.

JSON examples

Example 1 — Database metrics (Telegraf):

Example 2 — SNMP traffic (repeating ports):

Example 3 — Prometheus flat array:

3. Mapping Example 1 — One Node Per Repeating Field (new node per instance)

Use case: Each repeating fields entry creates a new node with its own metrics, differentiated by a tag field.

Input (Telegraf database metrics):

Mapping JSON:

Mapping field reference:

Output (Eyer internal format):

4. Mapping Example 2 — All Metrics on One Node (flatten into single node)

Use case: All repeating fields entries collapse onto the same node when the hostname tag is identical. Contrast with Example 1 which creates one node per instance.

Input (Telegraf SNMP traffic per switch port):

Mapping JSON:

Key difference vs Example 1: name_map is on the field level (not mapping level), which makes each field's name dynamically suffixed with the tag value (tags.ifName), collapsing all ports onto a single node.

Output (Eyer internal format):

5. Eyer Generic Input Format (no mapping needed)

Use this when you control the output format of your data source. No mapping file required — format directly to this schema and send to Eyer.

Rules

• All fields are mandatory

• NodeType must not contain spaces

• Timestamp must be in UNIX epoch format

• Aggregation values: avg, max, sum

Example

In this example: System = "Server 1", two node types (disk and CPU), multiple stat types per node.

To add more nodes: replace HD 1 with HD 2, CPU 1 with CPU 2, etc.

Once output is ready, send a sample to Eyer (support email or Discord) to get your endpoint enabled.

6. Mapping Example 3 — Using an LLM to Generate Mappings

An LLM (Claude, ChatGPT, Gemini, Mistral) can generate mapping JSON from your input data. The prompt pattern is:

1. Provide an example input JSON (your source data)

2. Provide an example mapping JSON (from Example 1 or 2 above)

3. Provide the expected output JSON (the mapped result)

4. Then ask: "How would the mapping look for this new input?"

Critical: Choose the example that matches the node topology you want. If you feed Example 1 to the LLM, it will produce one-node-per-instance mappings. If you feed Example 2, it will collapse to a single node.

LLM prompt template:

Resulting LLM output for an SNMP interface input (using Example 1 as reference):

Note: This LLM used Example 1 as the reference, so the result creates one node per switch port (tags.ifName). To get all ports on a single node, use Example 2 as the reference mapping instead.

After generating the mapping, always validate it with the Push API test endpoint (Section 7 below) before deploying.

7. Push API — Test and Validate Your Mapping

Use this endpoint to test a mapping against sample data before deploying. Returns the Eyer internal format so you can validate the node/metrics structure.

Endpoint:

Headers:

Request body structure:

Full example request (copy-paste ready):

8. Eyer Internal Data Format and Structure

All custom data, once mapped, is stored in the Eyer node→metrics structure.

Hierarchy:

• System — the host/server/device where the agent is installed

• Node — a monitored entity within the system (e.g., a database, network port, hard drive). Multiple nodes per system.

• Stats — one or more metrics per node (e.g., disk reads, CPU usage)

Internal format schema:

Concrete example (database server with one database node):

Quick Decision Reference