From 5bf770a789a64e84c850b79fc6688c21593ea1f6 Mon Sep 17 00:00:00 2001 From: sun Date: Thu, 18 Jun 2026 15:03:58 +0800 Subject: [PATCH] docs: Add GreptimeDB plugin docs Signed-off-by: sun --- docs/greptimedb/README.md | 46 ++++++ docs/greptimedb/go-sdk/datasource.md | 56 +++++++ docs/greptimedb/go-sdk/log-query.md | 65 ++++++++ docs/greptimedb/go-sdk/timeseries-query.md | 92 +++++++++++ docs/greptimedb/go-sdk/trace-query.md | 102 ++++++++++++ docs/greptimedb/model.md | 179 +++++++++++++++++++++ 6 files changed, 540 insertions(+) create mode 100644 docs/greptimedb/README.md create mode 100644 docs/greptimedb/go-sdk/datasource.md create mode 100644 docs/greptimedb/go-sdk/log-query.md create mode 100644 docs/greptimedb/go-sdk/timeseries-query.md create mode 100644 docs/greptimedb/go-sdk/trace-query.md create mode 100644 docs/greptimedb/model.md diff --git a/docs/greptimedb/README.md b/docs/greptimedb/README.md new file mode 100644 index 000000000..f964db49f --- /dev/null +++ b/docs/greptimedb/README.md @@ -0,0 +1,46 @@ +--- +tags: + - datasource +--- + +# GreptimeDB plugins + +The GreptimeDB package includes several plugins that provide comprehensive support for GreptimeDB in Perses dashboards. + +## Datasource (`GreptimeDBDatasource`) + +The GreptimeDB datasource enables connection between Perses and your GreptimeDB instance for SQL querying. It works with various visualization panels and supports SQL queries against the GreptimeDB HTTP SQL API (`POST /v1/sql`). + +It supports the [proxy](https://perses.dev/perses/docs/concepts/proxy/) feature of Perses that allows to restrict the access to your data source. + +See also technical docs related to this plugin: + +- [Data model](./model.md#greptimedbdatasource) +- [Dashboard-as-Code Go lib](./go-sdk/datasource.md) + +## Time Series Query (`GreptimeDBTimeSeriesQuery`) + +The GreptimeDB time series query plugin enables executing SQL queries against your GreptimeDB database for time-based data visualization. + +See also technical docs related to this plugin: + +- [Data model](./model.md#greptimedbtimeseriesquery) +- [Dashboard-as-Code Go lib](./go-sdk/timeseries-query.md) + +## Log Query (`GreptimeDBLogQuery`) + +The GreptimeDB log query plugin enables querying log data stored in your GreptimeDB database using SQL. + +See also technical docs related to this plugin: + +- [Data model](./model.md#greptimedblogquery) +- [Dashboard-as-Code Go lib](./go-sdk/log-query.md) + +## Trace Query (`GreptimeDBTraceQuery`) + +The GreptimeDB trace query plugin enables querying trace data stored in your GreptimeDB database using SQL. It works with trace visualization panels such as [Trace Table](../tracetable/README.md) and [Tracing Gantt Chart](../tracingganttchart/README.md). + +See also technical docs related to this plugin: + +- [Data model](./model.md#greptimedbtracequery) +- [Dashboard-as-Code Go lib](./go-sdk/trace-query.md) diff --git a/docs/greptimedb/go-sdk/datasource.md b/docs/greptimedb/go-sdk/datasource.md new file mode 100644 index 000000000..266f330eb --- /dev/null +++ b/docs/greptimedb/go-sdk/datasource.md @@ -0,0 +1,56 @@ +# GreptimeDB Datasource Go SDK + +## Constructor + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/datasource" + +var options []datasource.Option +datasource.GreptimeDB(options...) +``` + +Need a list of options. At least direct URL or proxy URL, in order to work. + +## Default options + +- None + +## Available options + +#### Direct URL + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/datasource" + +datasource.DirectURL("http://localhost:4000") +``` + +Configure the access to the GreptimeDB datasource with a direct URL. + +#### Proxy + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/datasource" + +datasource.HTTPProxy("https://current-domain-name.io", httpProxyOptions...) +``` + +Configure the access to the GreptimeDB datasource with a proxy URL. More info at [HTTP Proxy](https://perses.dev/perses/docs/dac/go/helper/http-proxy). + +## Example + +```golang +package main + +import ( + "github.com/perses/perses/go-sdk/dashboard" + + gtDs "github.com/perses/plugins/greptimedb/sdk/go/datasource" +) + +func main() { + dashboard.New("GreptimeDB Dashboard", + dashboard.AddDatasource("greptimeMain", gtDs.GreptimeDB(gtDs.DirectURL("http://localhost:4000"))), + ) +} +``` diff --git a/docs/greptimedb/go-sdk/log-query.md b/docs/greptimedb/go-sdk/log-query.md new file mode 100644 index 000000000..cb885db14 --- /dev/null +++ b/docs/greptimedb/go-sdk/log-query.md @@ -0,0 +1,65 @@ +# GreptimeDB Log Query Go SDK + +## Constructor + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/log" + +var options []log.Option +log.GreptimeDBLogQuery("SELECT * FROM greptime.public.logs LIMIT 100", options...) +``` + +Need to provide the SQL query expression and a list of options. + +## Default options + +- [Query()](#query): with the expression provided in the constructor. + +## Available options + +#### Query + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/log" + +log.Query("SELECT * FROM greptime.public.logs WHERE severity_text = 'ERROR' LIMIT 100") +``` + +Define the SQL query expression. + +#### Datasource + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/log" + +log.Datasource("MyGreptimeDBDatasource") +``` + +Define the datasource the query will use. + +## Example + +```golang +package main + +import ( + "github.com/perses/perses/go-sdk/dashboard" + "github.com/perses/perses/go-sdk/panel" + panelgroup "github.com/perses/perses/go-sdk/panel-group" + "github.com/perses/plugins/greptimedb/sdk/go/query/log" + logstable "github.com/perses/plugins/logstable/sdk/go" +) + +func main() { + dashboard.New("GreptimeDB Logs Dashboard", + dashboard.AddPanelGroup("Application Logs", + panelgroup.AddPanel("Recent logs", + logstable.LogsTable(), + panel.AddQuery( + log.GreptimeDBLogQuery("SELECT * FROM greptime.public.logs LIMIT 100"), + ), + ), + ), + ) +} +``` diff --git a/docs/greptimedb/go-sdk/timeseries-query.md b/docs/greptimedb/go-sdk/timeseries-query.md new file mode 100644 index 000000000..ed4dca4db --- /dev/null +++ b/docs/greptimedb/go-sdk/timeseries-query.md @@ -0,0 +1,92 @@ +# GreptimeDB Time Series Query Go SDK + +## Constructor + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/time-series" + +var options []timeseries.Option +timeseries.GreptimeDBTimeSeriesQuery(` + SELECT time_window, loc, + max(max_temp) RANGE '1m' FILL LINEAR AS max_temp + FROM public.temp_alerts + WHERE time_window >= to_timestamp_millis(${__from}) + AND time_window <= to_timestamp_millis(${__to}) + ALIGN '30s' BY (loc) + ORDER BY time_window ASC + LIMIT 2000 +`, options...) +``` + +Need to provide the SQL query expression and a list of options. + +## Default options + +- [Query()](#query): with the expression provided in the constructor. + +## Available options + +#### Query + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/time-series" + +timeseries.Query(` + SELECT time_window, loc, + max(max_temp) RANGE '1m' FILL LINEAR AS max_temp + FROM public.temp_alerts + WHERE time_window >= to_timestamp_millis(${__from}) + AND time_window <= to_timestamp_millis(${__to}) + ALIGN '30s' BY (loc) + ORDER BY time_window ASC + LIMIT 2000 +`) +``` + +Define the SQL query expression. `${__from}` and `${__to}` are replaced when the dashboard runs in Perses. + +#### Datasource + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/time-series" + +timeseries.Datasource("MyGreptimeDBDatasource") +``` + +Define the datasource the query will use. + +## Example + +```golang +package main + +import ( + "github.com/perses/perses/go-sdk/dashboard" + "github.com/perses/perses/go-sdk/panel" + panelgroup "github.com/perses/perses/go-sdk/panel-group" + "github.com/perses/plugins/greptimedb/sdk/go/query/time-series" + tsChart "github.com/perses/plugins/timeserieschart/sdk/go" +) + +func main() { + dashboard.New("GreptimeDB Dashboard", + dashboard.AddPanelGroup("Metrics", + panelgroup.AddPanel("Max temperature", + tsChart.Chart(), + panel.AddQuery( + timeseries.GreptimeDBTimeSeriesQuery(` + SELECT time_window, loc, + max(max_temp) RANGE '1m' FILL LINEAR AS max_temp + FROM public.temp_alerts + WHERE time_window >= to_timestamp_millis(${__from}) + AND time_window <= to_timestamp_millis(${__to}) + ALIGN '30s' BY (loc) + ORDER BY time_window ASC + LIMIT 2000 + `), + ), + ), + ), + ) +} +``` diff --git a/docs/greptimedb/go-sdk/trace-query.md b/docs/greptimedb/go-sdk/trace-query.md new file mode 100644 index 000000000..58dbd5ae9 --- /dev/null +++ b/docs/greptimedb/go-sdk/trace-query.md @@ -0,0 +1,102 @@ +# GreptimeDB Trace Query Go SDK + +## Constructor + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/trace" + +var options []trace.Option +trace.GreptimeDBTraceQuery("SELECT * FROM public.opentelemetry_traces LIMIT 100", options...) +``` + +Need to provide the SQL query expression and a list of options. + +## Default options + +- [Query()](#query): with the expression provided in the constructor. + +## Available options + +#### Query + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/trace" + +trace.Query("SELECT * FROM public.opentelemetry_traces WHERE trace_id = 'abc123' ORDER BY timestamp ASC") +``` + +Define the SQL query expression. + +#### Datasource + +```golang +import "github.com/perses/plugins/greptimedb/sdk/go/query/trace" + +trace.Datasource("MyGreptimeDBDatasource") +``` + +Define the datasource the query will use. + +## Example + +### Trace Table + +Use a trace list SQL query with the [Trace Table](../../tracetable/README.md) panel: + +```golang +package main + +import ( + "github.com/perses/perses/go-sdk/dashboard" + "github.com/perses/perses/go-sdk/panel" + panelgroup "github.com/perses/perses/go-sdk/panel-group" + "github.com/perses/plugins/greptimedb/sdk/go/query/trace" + tracetable "github.com/perses/plugins/tracetable/sdk/go" +) + +func main() { + dashboard.New("GreptimeDB Traces Dashboard", + dashboard.AddPanelGroup("Trace search", + panelgroup.AddPanel("Trace list", + tracetable.Chart(), + panel.AddQuery( + trace.GreptimeDBTraceQuery("SELECT * FROM public.opentelemetry_traces LIMIT 100"), + ), + ), + ), + ) +} +``` + +### Tracing Gantt Chart + +Use a trace detail SQL query (with a `trace_id` filter) with the [Tracing Gantt Chart](../../tracingganttchart/README.md) panel: + +```golang +package main + +import ( + "github.com/perses/perses/go-sdk/dashboard" + "github.com/perses/perses/go-sdk/panel" + panelgroup "github.com/perses/perses/go-sdk/panel-group" + "github.com/perses/plugins/greptimedb/sdk/go/query/trace" + tracinggantt "github.com/perses/plugins/tracingganttchart/sdk/go" +) + +func main() { + dashboard.New("GreptimeDB Trace Timeline Dashboard", + dashboard.AddPanelGroup("Trace details", + panelgroup.AddPanel("Trace timeline", + tracinggantt.Chart(), + panel.AddQuery( + trace.GreptimeDBTraceQuery(` + SELECT * FROM public.opentelemetry_traces + WHERE trace_id = 'abc123abc123abc123abc123abc123ab' + ORDER BY timestamp ASC + `), + ), + ), + ), + ) +} +``` diff --git a/docs/greptimedb/model.md b/docs/greptimedb/model.md new file mode 100644 index 000000000..665e1accb --- /dev/null +++ b/docs/greptimedb/model.md @@ -0,0 +1,179 @@ +# GreptimeDB plugin models + +This documentation provides the definition of the different plugins related to GreptimeDB. + +## GreptimeDBDatasource + +GreptimeDB as a datasource is an HTTP SQL API server. So we need to define an HTTP config. + +```yaml +kind: "GreptimeDBDatasource" +spec: + # It is the url of the datasource. + # Leave it empty if you don't want to access the datasource directly from the UI. + # You should define a proxy if you want to access the datasource through the Perses' server. + directUrl: # Optional + + # It is the http configuration that will be used by the Perses' server to redirect to the datasource any query sent by the UI. + proxy: # Optional +``` + +### HTTP Proxy specification + +See [common plugin definitions](https://perses.dev/perses/docs/plugins/common/#http-proxy-specification). + +### Example + +A simple GreptimeDB datasource would be + +```yaml +kind: "Datasource" +metadata: + name: "GreptimeDBMain" + project: "observability" +spec: + default: true + plugin: + kind: "GreptimeDBDatasource" + spec: + directUrl: "http://localhost:4000" +``` + +A more complex one: + +```yaml +kind: "Datasource" +metadata: + name: "GreptimeDBMain" + project: "observability" +spec: + default: true + plugin: + kind: "GreptimeDBDatasource" + spec: + proxy: + kind: "HTTPProxy" + spec: + url: "http://greptime.example.com:4000" + allowedEndpoints: + - endpointPattern: "/v1/sql" + method: "POST" + secret: "greptimedb_secret_config" +``` + +## GreptimeDBTimeSeriesQuery + +Perses supports time series queries for GreptimeDB: `GreptimeDBTimeSeriesQuery`. + +```yaml +kind: "GreptimeDBTimeSeriesQuery" +spec: + # `query` is the SQL expression for time series data. + query: + + # `datasource` is a datasource selector. If not provided, the default GreptimeDBDatasource is used. + # See the documentation about the datasources to understand how it is selected. + datasource: # Optional +``` + +- See [GreptimeDB Datasource selector](#greptimedb-datasource-selector) + +### Time range variables + +Time series queries can use Perses built-in time range variables in the SQL expression: `${__from}` and `${__to}`. They are replaced with the dashboard time picker start and end (Unix milliseconds) when the query runs. You do not need to create these variables manually. + +See also [Perses variable syntax](https://perses.dev/perses/docs/concepts/variable/#using-variables). + +### Example + +A time series query with GreptimeDB range alignment: + +```yaml +kind: "TimeSeriesQuery" +spec: + plugin: + kind: "GreptimeDBTimeSeriesQuery" + spec: + query: | + SELECT time_window, loc, + max(max_temp) RANGE '1m' FILL LINEAR AS max_temp + FROM public.temp_alerts + WHERE time_window >= to_timestamp_millis(${__from}) + AND time_window <= to_timestamp_millis(${__to}) + ALIGN '30s' BY (loc) + ORDER BY time_window ASC + LIMIT 2000 +``` + +## GreptimeDBLogQuery + +Perses supports log queries for GreptimeDB: `GreptimeDBLogQuery`. + +```yaml +kind: "GreptimeDBLogQuery" +spec: + # `query` is the SQL expression for log data. + query: + + # `datasource` is a datasource selector. If not provided, the default GreptimeDBDatasource is used. + # See the documentation about the datasources to understand how it is selected. + datasource: # Optional +``` + +- See [GreptimeDB Datasource selector](#greptimedb-datasource-selector) + +### Example + +A simple log query: + +```yaml +kind: "LogQuery" +spec: + plugin: + kind: "GreptimeDBLogQuery" + spec: + query: "SELECT * FROM greptime.public.logs LIMIT 100" +``` + +## GreptimeDBTraceQuery + +Perses supports trace queries for GreptimeDB: `GreptimeDBTraceQuery`. + +```yaml +kind: "GreptimeDBTraceQuery" +spec: + # `query` is the SQL expression for trace data. + query: + + # `datasource` is a datasource selector. If not provided, the default GreptimeDBDatasource is used. + # See the documentation about the datasources to understand how it is selected. + datasource: # Optional +``` + +- See [GreptimeDB Datasource selector](#greptimedb-datasource-selector) + +### Example + +A simple trace list query: + +```yaml +kind: "TraceQuery" +spec: + plugin: + kind: "GreptimeDBTraceQuery" + spec: + query: "SELECT * FROM public.opentelemetry_traces LIMIT 100" +``` + +## Shared definitions + +### GreptimeDB Datasource selector + +!!! note +See [Selecting / Referencing a Datasource](https://github.com/perses/perses/blob/main/docs/api/datasource.md#selecting--referencing-a-datasource) + +```yaml +kind: "GreptimeDBDatasource" +# The name of the datasource regardless its level +name: # Optional +```