Query and visualize AnyLog data in Grafana — increments/period/aggregations queries, blockchain visualizations, and importing sample dashboards.

title: “Grafana” description: “Connect Grafana to AnyLog and visualize distributed operational data and metadata.” layout: page —

Grafana

Grafana can be used to visualize operational data and metadata available through an AnyLog network.

Grafana connects to an AnyLog node through the AnyLog REST API. The connected node acts as a client to the AnyLog network and provides Grafana with access to distributed data without requiring Grafana to connect directly to each Operator or underlying database.

                         Grafana
                            │
                            │ REST
                            ▼
                       AnyLog Node
                            │
                     Metadata Lookup
                            │
               ┌────────────┼────────────┐
               ▼            ▼            ▼
           Operator 1   Operator 2   Operator 3
               │            │            │
               └────────────┼────────────┘
                            ▼
                      Unified Result
                            │
                            ▼
                         Grafana

AnyLog uses the network metadata to determine where the requested data is physically maintained, distributes the query to the relevant Operators, and returns a unified result to Grafana.

Grafana can be used to visualize:

time-series data,
tabular query results,
aggregated operational data,
data distributed across multiple tables and Operators,
AnyLog metadata,
and the geographic distribution of AnyLog nodes.

Prerequisites

To use Grafana with AnyLog, you need:

A running Grafana instance.
The Grafana JSON data source plugin supported by AnyLog.
An AnyLog node accessible from the Grafana server.
The AnyLog REST service running on that node.
Network access from Grafana to the AnyLog REST IP and port.

Running Grafana with Docker

The following example starts Grafana with the JSON data source and world map plugins:

docker run --name=grafana \
  -e GRAFANA_ADMIN_USER=admin \
  -e GRAFANA_ADMIN_PASSWORD=admin \
  -e GF_AUTH_DISABLE_LOGIN_FORM=false \
  -e GF_AUTH_ANONYMOUS_ENABLED=true \
  -e GF_SECURITY_ALLOW_EMBEDDING=true \
  -e GF_INSTALL_PLUGINS=simpod-json-datasource,grafana-worldmap-panel \
  -e GF_SERVER_HTTP_PORT=3000 \
  -v grafana-data:/var/lib/grafana \
  -v grafana-log:/var/log/grafana \
  -v grafana-config:/etc/grafana \
  -it -d -p 3000:3000 \
  grafana/grafana:9.5.16

Grafana is then available on port 3000.

For example:

http://localhost:3000

Configure the AnyLog REST Service

The AnyLog node used by Grafana must provide a REST connection.

The REST service is normally started as part of the node configuration.

For example:

<run rest server where
    external_ip=!external_ip and
    external_port=!anylog_rest_port and
    internal_ip=!ip and
    internal_port=!anylog_rest_port and
    bind=!rest_bind and
    threads=!rest_threads and
    timeout=!rest_timeout
>

The external IP and REST port must be reachable from the Grafana server.

Verify that the REST service is running:

get processes

Configure the Grafana Data Source

In Grafana:

Open Connections → Data Sources.
Add the JSON data source supported by the AnyLog Grafana interface.
Provide a unique name for the connection.
Set the URL to the REST address exposed by the AnyLog node.

For example:

http://10.0.0.25:2049

Optionally configure a default logical database using the Custom HTTP Headers supported by the AnyLog interface.
Select Save & Test.

A successful connection should report:

Data source is working

If no default database is specified, the databases accessible through the AnyLog node can be made available to Grafana.

The connected AnyLog node does not need to physically host the requested data. AnyLog uses the network metadata to locate the Operators that maintain the requested table.

Authentication

If authentication is enabled on the AnyLog REST interface, configure the Grafana data source with the corresponding authentication settings.

For REST authentication using username and password, enable Basic Auth in the Grafana data source.

When using SSL certificates, configure the corresponding TLS options in Grafana, including TLS Client Auth when required.

The Grafana authentication configuration must match the authentication and security configuration of the AnyLog REST service.

Troubleshooting the Connection

If Save & Test fails, verify:

the AnyLog node is running,
the REST service is running,
the configured REST IP and port are correct,
the REST port is reachable from the Grafana server,
firewall rules allow the connection,
Grafana authentication settings match the AnyLog REST configuration,
the AnyLog node has synchronized metadata,
and the requested databases and tables are represented in the metadata.

Useful AnyLog commands include:

get processes
test node
test network
blockchain get table

If Grafana reports:

Error: No table connected

verify that the connected AnyLog node can discover the tables associated with the selected logical database.

Querying AnyLog from Grafana

Grafana can present AnyLog data primarily in two formats:

Time Series — values displayed as a function of time.
Table — query results displayed as rows and columns.

AnyLog provides predefined query types optimized for Grafana, including:

increments
period

Grafana can also issue custom SQL queries and AnyLog metadata requests.

Query behavior is controlled using the panel’s Additional JSON Data.

Additional JSON Data

The Additional JSON Data payload provides instructions to AnyLog about how the query should be executed.

For example:

{
  "type": "increments",
  "time_column": "timestamp",
  "value_column": "value",
  "grafana": {
    "format_as": "timeseries",
    "data_points": 1000
  }
}

Common attributes include:

Attribute	Description
`dbms`	Logical database to query. Overrides the default database configured for the data source.
`table`	Table to query. Overrides the table selected or specified by the SQL statement.
`type`	Query type, such as `increments`, `period`, `info`, or `map`.
`sql`	SQL statement to execute.
`details`	AnyLog command to execute instead of SQL.
`where`	Additional SQL `WHERE` condition.
`functions`	List of aggregation functions to apply.
`timezone`	Determines timestamp handling.
`time_column`	Timestamp column used by time-series queries.
`value_column`	Value column used by the visualization.
`time_range`	Determines whether the Grafana-selected time range is applied.
`servers`	Explicitly identifies Operators instead of using metadata-based routing.
`include`	Adds additional tables to the logical query.
`extend`	Adds source metadata to the returned rows.
`instructions`	Additional AnyLog query instructions.
`grafana.format_as`	Grafana result format, typically `timeseries` or `table`.
`grafana.data_points`	Approximate number of data points requested from an `increments` query.

Values in Additional JSON Data override corresponding default values where applicable.

Time-Series Visualization

Increments Query

The increments query is designed for visualizing time-series data over a selected Grafana time range.

AnyLog divides the requested time range into intervals and applies functions such as min, max, and avg to each interval.

A basic payload is:

{
  "type": "increments",
  "time_column": "timestamp",
  "value_column": "value",
  "grafana": {
    "format_as": "timeseries",
    "data_points": 1000
  }
}

AnyLog translates the Grafana request into a distributed SQL query.

Conceptually, the generated query is similar to:

SELECT
    increments(second, 1, timestamp),
    max(timestamp) AS timestamp,
    avg(value) AS avg_val,
    min(value) AS min_val,
    max(value) AS max_val
FROM percentagecpu_sensor
WHERE
    timestamp >= '2024-02-19T19:42:02.133Z'
    AND timestamp <= '2024-02-19T19:57:02.133Z'
LIMIT 2128;

The actual interval is determined from the requested time range and query configuration.

Data Points

The data_points attribute allows AnyLog to dynamically determine an appropriate interval for an increments query.

For example:

{
  "type": "increments",
  "time_column": "timestamp",
  "value_column": "value",
  "grafana": {
    "format_as": "timeseries",
    "data_points": 1000
  }
}

AnyLog attempts to return approximately the requested number of time buckets.

This provides a balance between:

query performance,
graph resolution,
and the amount of data returned to Grafana.

If data_points is not specified, the Grafana interval configured in Query Options is used.

Grafana’s Max data points setting may also limit the number of rows displayed.

Query Multiple Tables

The include option allows multiple tables to be processed as a single logical query.

For example:

{
  "type": "increments",
  "time_column": "timestamp",
  "value_column": "value",
  "extend": ["@table_name"],
  "include": ["t98"],
  "grafana": {
    "format_as": "timeseries"
  }
}

If the selected table is t99, the query processes data from both:

t99
t98

The corresponding AnyLog distributed query includes:

run client () sql nov timezone = utc and pass_through = false and include = (t98) and extend = (@dbms_name,@table_name)

followed by the SQL statement.

The include option is useful when operational data with the same logical structure is distributed across multiple tables.

Extend Query Results with Source Metadata

The extend option adds metadata about the source of each returned row.

For example:

{
  "type": "increments",
  "time_column": "timestamp",
  "value_column": "value",
  "extend": ["@table_name"],
  "grafana": {
    "format_as": "timeseries"
  }
}

This allows Grafana to preserve information about where each value originated.

Depending on the query, extensions can include values such as:

@dbms_name
@table_name
@ip

This is particularly useful when a Grafana panel combines data from multiple tables, nodes, or data sources.

Add a WHERE Condition

Additional filtering can be applied using where.

For example:

{
  "type": "increments",
  "time_column": "timestamp",
  "value_column": "value",
  "where": "device_name='ADVA FSP3000R7'",
  "grafana": {
    "format_as": "timeseries"
  }
}

The condition is added to the SQL query generated for the panel.

Period Query

A period query retrieves values associated with the end of the selected time range.

If a value is not available exactly at the end of the range, AnyLog identifies the latest available time and calculates the requested statistics for the corresponding period.

For example:

{
  "type": "period",
  "time_column": "timestamp",
  "value_column": "value",
  "grafana": {
    "format_as": "timeseries"
  }
}

The resulting SQL is conceptually similar to:

SELECT
    max(timestamp) AS timestamp,
    avg(value) AS avg_val,
    min(value) AS min_val,
    max(value) AS max_val
FROM ping_sensor;

period queries are useful for Grafana visualizations such as:

Gauge
Stat
Current-value panels

Period Query with Filtering

A where condition can also be applied to a period query:

{
  "type": "period",
  "time_column": "timestamp",
  "value_column": "value",
  "where": "device_name='ADVA FSP3000R7'",
  "grafana": {
    "format_as": "timeseries"
  }
}

Specify Aggregation Functions

The functions applied by a query can be explicitly specified.

For example:

{
  "type": "period",
  "time_column": "timestamp",
  "value_column": "value",
  "time_range": false,
  "functions": ["min", "max", "avg", "count"],
  "grafana": {
    "format_as": "timeseries"
  }
}

In this example:

"time_range": false

instructs AnyLog not to restrict the query using the Grafana-selected time range.

Metadata Visualization

Grafana can also visualize the AnyLog metadata layer.

This allows dashboards to display information about the network itself, including nodes, locations, clusters, and other metadata policies.

The metadata may be maintained by either an AnyLog Master Node or a blockchain platform. The same AnyLog metadata commands are used in either configuration.

Network Map from Metadata

A Grafana Geomap panel can display the geographic distribution of AnyLog nodes.

In Grafana:

Create or edit a panel.
Select Geomap as the visualization.
Select a table in the Metric section.
Add the following payload:

{
  "type": "map",
  "member": ["master", "query", "operator", "publisher"],
  "metric": [0, 0, 0],
  "attribute": ["name", "name", "name", "name"]
}

AnyLog retrieves the relevant node metadata and returns the information required by the map visualization.

Metadata Table

A Grafana Table panel can display AnyLog metadata policies.

For example, to display Operator information:

{
  "type": "info",
  "details": "blockchain get operator bring.json [*][cluster] [*][name] [*][company] [*][ip] [*][country] [*][state] [*][city]"
}

The details attribute contains an AnyLog command rather than SQL.

In this example, Grafana receives information describing Operators, including:

cluster,
name,
company,
IP,
country,
state,
and city.

Although the command is named blockchain get, it queries the AnyLog metadata available to the node and works with metadata synchronized from either a Master Node or a blockchain platform.

Using a Different Logical Database

A Grafana data source can be configured with a default logical database.

A panel can override that database using dbms.

For example:

{
  "dbms": "manufacturing",
  "type": "increments",
  "time_column": "timestamp",
  "value_column": "temperature",
  "grafana": {
    "format_as": "timeseries"
  }
}

AnyLog then resolves the requested table within the manufacturing logical database.

1. Current-Value Gauge

Use:

{
  "type": "period",
  "time_column": "timestamp",
  "value_column": "value",
  "grafana": {
    "format_as": "timeseries"
  }
}

2. Operator Metadata Table

Use:

{
  "type": "info",
  "details": "blockchain get operator bring.json [*][name] [*][company] [*][ip] [*][cluster]"
}

Together, these panels verify:

REST connectivity,
metadata access,
distributed SQL processing,
time-series formatting,
and metadata queries.

Troubleshooting Queries

If Grafana is connected but a panel does not return data, first verify that AnyLog can discover the requested table:

blockchain get table

Verify the network:

test network

Check the node services:

get processes

Review errors:

get error log

For distributed SQL, the equivalent query can also be tested directly from the AnyLog CLI:

run client () sql <dbms> format = table and stat = <SQL statement>

Testing the query from the CLI helps determine whether an issue is related to the AnyLog query itself or to the Grafana panel configuration.

SQL Commands — distributed SQL syntax and query options.
Blockchain & Metadata — metadata policies, synchronization, and metadata commands.
Unified Namespace — logical navigation over distributed operational data.
REST API — configuring and using the AnyLog REST interface.
Networking & Security — authentication, TLS, permissions, and network configuration.

Grafana

Prerequisites

Running Grafana with Docker

Configure the AnyLog REST Service

Configure the Grafana Data Source

Authentication

Troubleshooting the Connection

Querying AnyLog from Grafana

Additional JSON Data

Time-Series Visualization

Increments Query

Data Points

Query Multiple Tables

Extend Query Results with Source Metadata

Add a WHERE Condition

Period Query

Period Query with Filtering

Specify Aggregation Functions

Metadata Visualization

Network Map from Metadata

Metadata Table

Using a Different Logical Database

1. Current-Value Gauge

2. Operator Metadata Table

Troubleshooting Queries

Related Documentation

node_configs.env