Monitoring Integration

Tidecoin Core exposes operational state through JSON-RPC, logs, optional REST, and optional ZMQ. It does not expose Prometheus metrics natively. Monitoring systems should collect a small set of RPC probes, ship debug.log, and alert on node health, sync progress, peer connectivity, disk pressure, and chain splits.

This page is for integrating external monitoring systems. It is not the operator runbook for what each alert means; that belongs in Node & Operations / Monitoring.

Collection architecture

Use one of these patterns:

Pattern	Use when	Notes
RPC exporter	You already run Prometheus or Grafana Agent.	Poll selected JSON-RPC commands and convert fields to metrics.
Textfile collector	You run node exporter.	A cron or systemd timer writes selected metrics to a `.prom` file.
Log pipeline	You use Loki, Elasticsearch, or another aggregator.	Ship `debug.log` and parse warnings, validation errors, and reorg messages.
ZMQ subscriber	You need low-latency block or transaction events.	Use ZMQ for event notification, then confirm state through RPC.

Keep monitoring RPC credentials read-only. The monitoring user should be allowed to call health and introspection commands only.

RPC probes

Minimum probes:

RPC	Fields to collect	Alert use
`getblockchaininfo`	`chain`, `blocks`, `headers`, `bestblockhash`, `initialblockdownload`, `verificationprogress`, `pruned`, `size_on_disk`, `warnings`	Sync state, chain identity, IBD, disk growth, warnings.
`getnetworkinfo`	`connections`, `connections_in`, `connections_out`, `networkactive`, `warnings`	Peer health and network isolation.
`getmempoolinfo`	`size`, `bytes`, `usage`, `mempoolminfee`, `minrelaytxfee`	Mempool pressure and fee floor changes.
`getchaintips`	Active and stale tips	Fork and reorg observation.
`getmininginfo`	`difficulty`, `networkhashps`, chain mining fields	Mining and difficulty visibility where available.
`getrpcinfo`	Active commands	Stuck or abusive RPC clients.
`uptime`	Process uptime seconds	Restart detection.

For integrations that depend on indexes, also collect getindexinfo if the configured node exposes it.

Example metric names

Exporter names do not need to match these exactly, but stable names make dashboards and alerts maintainable:

Metric	Type	Source
`tidecoin_block_height`	Gauge	`getblockchaininfo.blocks`.
`tidecoin_header_height`	Gauge	`getblockchaininfo.headers`.
`tidecoin_initial_block_download`	Gauge	`getblockchaininfo.initialblockdownload`.
`tidecoin_verification_progress`	Gauge	`getblockchaininfo.verificationprogress`.
`tidecoin_peer_count`	Gauge	`getnetworkinfo.connections`.
`tidecoin_network_active`	Gauge	`getnetworkinfo.networkactive`.
`tidecoin_mempool_transactions`	Gauge	`getmempoolinfo.size`.
`tidecoin_mempool_bytes`	Gauge	`getmempoolinfo.bytes`.
`tidecoin_disk_size_bytes`	Gauge	`getblockchaininfo.size_on_disk`.
`tidecoin_process_uptime_seconds`	Gauge	`uptime`.

Expose the chain name as a label only when the label cardinality is controlled, for example chain="main", chain="test", or chain="regtest".

Prometheus scrape shape

If you deploy an RPC exporter on the node host, a minimal scrape target looks like:


scrape_configs:
  - job_name: tidecoin
    static_configs:
      - targets:
          - 127.0.0.1:9332

The port above is the exporter port, not the Tidecoin RPC port. Do not expose Tidecoin JSON-RPC directly as a Prometheus target.

Alert rules

Start with these alerts and tune thresholds for the environment:

Alert	Condition
Node down	Exporter cannot reach the node or `uptime` stops responding.
In IBD	`initialblockdownload` remains true after the expected sync window.
Header lag	`headers - blocks` stays above the threshold.
Low peers	Peer count stays below the service threshold.
Network inactive	`networkactive` is false.
Chain mismatch	`chain` is not the expected network.
Node split	Two exchange-controlled nodes report different best block hashes for longer than the tolerance window.
Disk pressure	Free disk space or projected chain data growth crosses the threshold.
Warnings present	`warnings` is non-empty.
Deep reorg	Reorg depth exceeds the integration’s configured tolerance.

For exchanges and custodians, alert on fleet disagreement, not only single-node health. A single healthy but isolated node is not enough to safely credit deposits.

Log integration

Ship the node’s debug.log to the same retention system used for other infrastructure logs. Useful filters include:

Pattern	Meaning
`UpdateTip`	Normal tip advancement.
`REORGANIZE` or reorg-related messages	Chain reorganization.
`ERROR`, `Error`, `failed`	Operational or validation failure.
`Misbehaving` / peer disconnect messages	Peer health.
AuxPoW reject reasons	Merged-mining integration failures after activation.

Avoid alerting on every log line containing error until the filters are tested against production-like logs; debug logs can include benign context.

ZMQ event feeds

Use ZMQ for low-latency notifications, then confirm details through RPC. ZMQ is useful for:

Topic class	Use
New block notifications	Trigger block ingestion immediately.
Mempool transaction notifications	Update unconfirmed transaction UX.
Sequence notifications	Track mempool add/remove events where supported.

ZMQ is not a replacement for a reorg-aware block index. Missed notifications, subscriber restarts, and network interruptions must be recovered by comparing stored tip state against getblockchaininfo.

Security

Monitoring credentials should not be able to spend, import keys, submit blocks, or change node state. Use RPC whitelisting for monitoring service accounts and bind RPC to localhost or a private network. See RPC Security for configuration examples.

Source of truth

Topic	Canonical page
Operator monitoring runbook	Node & Operations / Monitoring
RPC security	RPC Security
REST and ZMQ enablement	Node & Operations / REST and ZMQ
RPC polling patterns	RPC Integration Patterns
RPC command schemas	RPC Reference