Skip to main content

YAML Configuration Structure (v0.2.0)

This document details the structure of the YAML configuration file used to set up your Ikura monitoring projects. We'll go through the different sections and fields available.

The current and only supported configuration version right now is 0.2.0.

You can always view the raw JSON Schema definition here for technical details.

Beta Feature: Node Monitoring

Please be aware that the Node Monitoring feature (nodes section in the config) is currently in Beta.

  • Functionality: It might not work perfectly as expected yet.
  • Stability: There's a possibility it could cause issues with your project dashboard display.
  • Changes: The configuration options or behavior for nodes might change in future updates based on feedback.

Use the node monitoring feature with these points in mind. RPC monitoring is stable.

Top-Level Project Fields​

These fields define the overall project settings.

  • version (string, Required)
    • The configuration schema version. Must be exactly "0.2.0".
    • Example: version: 0.2.0
  • label (string, Required)
    • A human-readable name for your project, displayed in the Ikura UI.
    • Must be between 3 and 30 characters long.
    • Example: label: My Production Ethereum Watcher
  • slug (string, Required)
    • A unique identifier for the project, used internally and potentially in URLs. If omitted, Ikura might generate one.
    • Allowed characters: letters (a-z, A-Z), numbers (0-9), hyphen (-), underscore (_).
    • Must be between 3 and 30 characters long.
    • Example: slug: prod-eth-watcher
  • links (object, Optional)
    • An object containing relevant URLs for your project.
    • Allowed keys: web, app, docs, github, twitter, discord, telegram.
    • Values should be valid URIs (e.g., https://..., http://...).
    • Example: 
      links:
        web: https://myproject.com
        github: https://github.com/myproject
  • tags (array of string, Optional)
    • A list of tags (up to 10) to categorize your project.
    • Each tag must be 3-25 characters long, lowercase letters (a-z), numbers (0-9), and hyphens (-) only. Tags must be unique within the list.
    • Example: tags: [mainnet, ethereum, layer-1]
  • logo (string, Optional)
    • A URL pointing to an image file (jpg, jpeg, png, webp, svg) to be used as the project logo. Max length 200 characters.
    • Example: logo: https://myproject.com/logo.png
  • rpcs (array of object, Optional)
    • A list of public RPC endpoints to monitor. See the RPC Endpoint section below for details on the object structure.
  • nodes (object, Optional)
    • A map (key-value pairs) defining private nodes to monitor. See the Node (Beta) section below for details.
Project Requirement

Your project configuration must include at least one of the following:

  • An rpcs list with one or more endpoints.
  • A nodes object with one or more node definitions. You can also include both.

RPC Endpoint​

Defines a single public RPC endpoint to monitor within the rpcs list.

  • url (string, Required)
    • The full URL of the RPC endpoint.
    • Must start with http://, https://, ws://, or wss://. Can also be a specific drpc.org URL format.
    • Example: url: https://rpc.ankr.com/eth
  • label (string, Required)
    • A human-readable name for this specific RPC endpoint in the UI.
    • Example: label: Ankr Public ETH RPC
  • protocol (string, Required)
    • Specifies the type of API the endpoint provides. This determines which checks Ikura performs.
    • Allowed values (defined in schema): ethereum_v1, ethereum_v2, op_node, subgraph, subquery, substrate, starkware, tendermint, web.
    • Example: protocol: ethereum_v1
  • query_intervals (object, Required)
    • Specifies how often Ikura should query the endpoint. See Query Intervals below.
  • headers (object, Optional)
    • Custom HTTP headers to include when querying the endpoint.
    • Supported keys: authorization (e.g., Bearer ..., Basic ...), origin. Values are strings.
    • Example: 
      headers:
        authorization: Bearer YOUR_API_KEY
  • bundle (string, Optional)
    • An identifier used to group related RPC endpoints visually on the status page (e.g., different RPCs for the same network). Allowed characters: a-z, A-Z, 0-9, -, _.
    • Example: bundle: mainnet-eth-public
  • bhead (boolean, Optional)
    • Stands for "Bundle Head". If true, this RPC endpoint might be used as the primary representative for status display when grouped in a bundle. Default is false.
    • Example: bhead: true
  • chain_id (string, Optional)
    • The expected Chain ID (for EVM-compatible chains). Ikura can verify this against the ID reported by the node. Allowed characters: a-z, A-Z, 0-9, -, _.
    • Generates an alert if the reported Chain ID doesn't match.
    • Example: chain_id: 1 # Ethereum Mainnet

Query Intervals​

Defined within an rpc object under the query_intervals key. Specifies check frequencies in seconds.

  • latest_block (number, Required)
    • How often to check the latest block number (e.g., using eth_blockNumber).
    • Value must be a multiple of 5, and the minimum allowed value is 10.
    • Example: latest_block: 15 # Check every 15 seconds
  • meta (number, Optional)
    • How often to check other metadata (like sync status, peer count, etc., depending on the protocol).
    • Value must be a multiple of 60, and the minimum allowed value is 60.
    • Example: meta: 300 # Check every 5 minutes
Careful with Intervals and Provider Costs!

Using short intervals (like checking latest_block every 10 seconds) can result in a high volume of requests to the RPC provider.

  • latest_block @ 10s = ~8,640 requests/day.
  • meta @ 60s = ~1,440 requests/day (actual count depends on protocol specifics).

Be mindful of your RPC provider's rate limits and potential costs! Adjust intervals based on your needs and budget.

Node (Not Stable)​

Beta Feature Reminder

As mentioned at the top, Node Monitoring is in Beta. Expect potential instability or changes.

Defines a single private node to monitor. These are placed inside the top-level nodes object, where each key is a unique identifier you choose for that node within the config file.

  • [node_key] (string, Map Key)

    • This key (e.g., mainnet-exec-node in the example) is how you identify the node within this YAML file. It's used to link with the Ikura Keeper agent configuration.
    • Allowed characters: letters (a-z, A-Z), numbers (0-9), hyphen (-), underscore (_).

  • label (string, Required)

    • A human-readable name for this node displayed in the Ikura UI.
    • Example: label: AWS Mainnet Execution Client

  • protocol (string, Required)

    • Specifies the type of node the agent is monitoring.
    • Allowed values (defined in schema): ethereum_v1, ethereum_v2, op_node.
    • Example: protocol: ethereum_v2 # For a consensus client
    Protocol Implementation Status

    While the schema defines these, ensure your Ikura Keeper agent version supports the chosen protocol. ethereum_v1 and ethereum_v2 are the primary focus currently.

  • bundle (string, Optional)

    • An identifier used to group related nodes (like an execution and consensus client pair for Ethereum). Provides better status overview for the bundle. Allowed characters: a-z, A-Z, 0-9, -, _.
    • Example: bundle: mainnet-validator-1

  • bhead (boolean, Optional)

    • "Bundle Head". If true, this node might represent the bundle's overall status. Default is false.
    • Example: bhead: true

  • uuid (string format uuid, Optional)

    • A universally unique identifier (UUID) for this node. This is crucial for data continuity.
    • How it works:
      • If you don't provide a uuid, Ikura generates one when the project is first created. You'll need to copy this generated UUID into your Ikura Keeper agent config for that node.
      • If you do provide a uuid, Ikura uses it to track the node's history, even if you change its [node_key] in the YAML later.
    • Example: uuid: 415fd1a6-d442-4163-b2b6-dbc6d9884da1
    Managing Node Identity with uuid
    • Changing [node_key] without uuid: If you change the key (e.g., mainnet-exec-node to prod-exec-node) and haven't specified a uuid in your YAML, Ikura will treat it as a brand new node. You'll lose the historical data for the old key, and you'll need to update the agent config with the new generated UUID.
    • Keeping History: To rename a node ([node_key]) but keep its history, you MUST first find the generated uuid (e.g., from the UI or previous agent config) and add it to the YAML before changing the key.
    uuid: Simple vs. Persistent
    • Don't care about history? Just let Ikura generate the uuid on creation and copy it to your agent config. Don't worry about adding it to the YAML.
    • Want history persistence (especially if renaming)? Make sure the correct uuid is present in both your project YAML and the agent config for that node.

  • block_time_ms (number, Optional)

    • Expected block time in milliseconds (minimum 10). Used for reference and uptime checks. Currently not supported yet.
    • Example: block_time_ms: 12000 # For Ethereum PoS

  • block_interval_seconds (number, Optional)

    • Expected interval between blocks in seconds (minimum 1). Used for reference and uptime checks. Currently not supported yet.
    • Example: block_interval_seconds: 2 # For Optimism/OP Stack

Examples​

In the following project YAML config example the node keys are mainnet-eth-1-consensus and mainnet-eth-1-execution:

nodes:
  mainnet-eth-1-execution:
    label: AWS Mainnet ETH Execution
    protocol: ethereum_v1
    bundle: mainnet-eth-1
  mainnet-eth-1-consensus:
    label: AWS Mainnet ETH Consensus
    protocol: ethereum_v1
    bundle: mainnet-eth-1

The corresponding Ikura Keeper config on you server cold look like:

secret: wZz0NCZD7fGyWqrOvORB4JOx51dgYs80spgEpoTm87
nodes:
  mainnet-eth-1-execution:
    rpc: http://localhost:8545
    id: 415fd1a6-d442-4163-b2b6-dbc6d9884da1
    protocol: ethereum_v1
  mainnet-eth-1-consensus:
    rpc: http://localhost:9000
    id: 415fd1a6-d442-4163-b2b6-dbc6d9884da1
    protocol: ethereum_v2
Last updated on