快速开始

在继续阅读之前，请确保你已经安装了 GreptimeDB。

本指南通过引导你创建一个 metric 表和一个 log 表来介绍 GreptimeDB 的核心功能。

连接到 GreptimeDB

GreptimeDB 支持多种协议与数据库进行交互。 在本快速入门文档中，我们使用 SQL 作为实例。

如果你的 GreptimeDB 实例运行在 127.0.0.1 中， 并且使用 MySQL 客户端默认端口 4002 或 PostgreSQL 客户端默认端口 4003， 你可以使用以下命令连接到数据库。

GreptimeDB 默认不开启鉴权认证。 在本章节中你可以在连接数据库时不提供用户名密码。

  1. mysql -h 127.0.0.1 -P 4002

或者

  1. psql -h 127.0.0.1 -p 4003 -d public

创建表

假设你有一个名为 grpc_latencies 的表，用于存储的 gRPC 延迟。表 schema 如下：

  1. CREATE TABLE grpc_latencies (
  2.   ts TIMESTAMP TIME INDEX,
  3.   host STRING,
  4.   method_name STRING,
  5.   latency DOUBLE,
  6.   PRIMARY KEY (host, method_name)
  7. )
  8. engine=mito with('append_mode'='true');
  • ts：收集指标时的时间戳，时间索引列。
  • host：主机名，tag 列。
  • method_name：RPC 请求方法的名称，tag 列。
  • latency：RPC 请求的延迟。

此外，还有一个名为 app_logs 的表用于存储日志：

  1. CREATE TABLE app_logs (
  2.   ts TIMESTAMP TIME INDEX,
  3.   host STRING,
  4.   api_path STRING FULLTEXT,
  5.   log_level STRING,
  6.   log STRING FULLTEXT,
  7.   PRIMARY KEY (host, log_level)
  8. )
  9. engine=mito with('append_mode'='true');
  • ts：日志条目的时间戳，时间索引列。
  • host：主机名，tag 列。
  • api_path：API 路径，使用 FULLTEXT 进行索引以加速搜索。
  • log_level：日志级别，tag 列。
  • log：日志消息，使用 FULLTEXT 进行索引以加速搜索。

写入数据

让我们插入一些模拟数据来模拟收集的指标和错误日志。

假设有两个服务器 host1 和 host2 记录着 gRPC 延迟。 从 2024-07-11 20:00:10 开始，host1 的延迟显著增加。

下图显示了 host1 的不稳定延迟。

unstable latencies

使用以下 SQL 语句插入模拟数据。

在 2024-07-11 20:00:10 之前，主机正常运行：

  1. INSERT INTO grpc_latencies (ts, host, method_name, latency) VALUES
  2.   ('2024-07-11 20:00:06', 'host1', 'GetUser', 103.0),
  3.   ('2024-07-11 20:00:06', 'host2', 'GetUser', 113.0),
  4.   ('2024-07-11 20:00:07', 'host1', 'GetUser', 103.5),
  5.   ('2024-07-11 20:00:07', 'host2', 'GetUser', 107.0),
  6.   ('2024-07-11 20:00:08', 'host1', 'GetUser', 104.0),
  7.   ('2024-07-11 20:00:08', 'host2', 'GetUser', 96.0),
  8.   ('2024-07-11 20:00:09', 'host1', 'GetUser', 104.5),
  9.   ('2024-07-11 20:00:09', 'host2', 'GetUser', 114.0);

在 2024-07-11 20:00:10 之后，host1 的延迟变得不稳定：

  2. INSERT INTO grpc_latencies (ts, host, method_name, latency) VALUES
  3.   ('2024-07-11 20:00:10', 'host1', 'GetUser', 150.0),
  4.   ('2024-07-11 20:00:10', 'host2', 'GetUser', 110.0),
  5.   ('2024-07-11 20:00:11', 'host1', 'GetUser', 200.0),
  6.   ('2024-07-11 20:00:11', 'host2', 'GetUser', 102.0),
  7.   ('2024-07-11 20:00:12', 'host1', 'GetUser', 1000.0),
  8.   ('2024-07-11 20:00:12', 'host2', 'GetUser', 108.0),
  9.   ('2024-07-11 20:00:13', 'host1', 'GetUser', 80.0),
  10.   ('2024-07-11 20:00:13', 'host2', 'GetUser', 111.0),
  11.   ('2024-07-11 20:00:14', 'host1', 'GetUser', 4200.0),
  12.   ('2024-07-11 20:00:14', 'host2', 'GetUser', 95.0),
  13.   ('2024-07-11 20:00:15', 'host1', 'GetUser', 90.0),
  14.   ('2024-07-11 20:00:15', 'host2', 'GetUser', 115.0),
  15.   ('2024-07-11 20:00:16', 'host1', 'GetUser', 3000.0),
  16.   ('2024-07-11 20:00:16', 'host2', 'GetUser', 95.0),
  17.   ('2024-07-11 20:00:17', 'host1', 'GetUser', 320.0),
  18.   ('2024-07-11 20:00:17', 'host2', 'GetUser', 115.0),
  19.   ('2024-07-11 20:00:18', 'host1', 'GetUser', 3500.0),
  20.   ('2024-07-11 20:00:18', 'host2', 'GetUser', 95.0),
  21.   ('2024-07-11 20:00:19', 'host1', 'GetUser', 100.0),
  22.   ('2024-07-11 20:00:19', 'host2', 'GetUser', 115.0),
  23.   ('2024-07-11 20:00:20', 'host1', 'GetUser', 2500.0),
  24.   ('2024-07-11 20:00:20', 'host2', 'GetUser', 95.0);

当 host1 的 gRPC 请求的延迟遇到问题时，收集了一些错误日志。

  1. INSERT INTO app_logs (ts, host, api_path, log_level, log) VALUES
  2.   ('2024-07-11 20:00:10', 'host1', '/api/v1/resource', 'ERROR', 'Connection timeout'),
  3.   ('2024-07-11 20:00:10', 'host1', '/api/v1/billings', 'ERROR', 'Connection timeout'),
  4.   ('2024-07-11 20:00:11', 'host1', '/api/v1/resource', 'ERROR', 'Database unavailable'),
  5.   ('2024-07-11 20:00:11', 'host1', '/api/v1/billings', 'ERROR', 'Database unavailable'),
  6.   ('2024-07-11 20:00:12', 'host1', '/api/v1/resource', 'ERROR', 'Service overload'),
  7.   ('2024-07-11 20:00:12', 'host1', '/api/v1/billings', 'ERROR', 'Service overload'),
  8.   ('2024-07-11 20:00:13', 'host1', '/api/v1/resource', 'ERROR', 'Connection reset'),
  9.   ('2024-07-11 20:00:13', 'host1', '/api/v1/billings', 'ERROR', 'Connection reset'),
  10.   ('2024-07-11 20:00:14', 'host1', '/api/v1/resource', 'ERROR', 'Timeout'),
  11.   ('2024-07-11 20:00:14', 'host1', '/api/v1/billings', 'ERROR', 'Timeout'),
  12.   ('2024-07-11 20:00:15', 'host1', '/api/v1/resource', 'ERROR', 'Disk full'),
  13.   ('2024-07-11 20:00:15', 'host1', '/api/v1/billings', 'ERROR', 'Disk full'),
  14.   ('2024-07-11 20:00:16', 'host1', '/api/v1/resource', 'ERROR', 'Network issue'),
  15.   ('2024-07-11 20:00:16', 'host1', '/api/v1/billings', 'ERROR', 'Network issue');

查询数据

根据 tag 和时间索引进行过滤

你可以使用 WHERE 子句来过滤数据。例如，要查询 2024-07-11 20:00:15 之后 host1 的延迟：

  1. SELECT *
  2.   FROM grpc_latencies
  3.   WHERE host = 'host1' AND ts > '2024-07-11 20:00:15';
  1. +---------------------+-------+-------------+---------+
  2. | ts                  | host  | method_name | latency |
  3. +---------------------+-------+-------------+---------+
  4. | 2024-07-11 20:00:16 | host1 | GetUser     |    3000 |
  5. | 2024-07-11 20:00:17 | host1 | GetUser     |     320 |
  6. | 2024-07-11 20:00:18 | host1 | GetUser     |    3500 |
  7. | 2024-07-11 20:00:19 | host1 | GetUser     |     100 |
  8. | 2024-07-11 20:00:20 | host1 | GetUser     |    2500 |
  9. +---------------------+-------+-------------+---------+
  10. 5 rows in set (0.14 sec)

你还可以在过滤数据时使用函数。例如，你可以使用 approx_percentile_cont 函数按主机分组计算延迟的第 95 百分位数：

  1. SELECT 
  2.   approx_percentile_cont(latency, 0.95) AS p95_latency, 
  3.   host
  4. FROM grpc_latencies
  5. WHERE ts >= '2024-07-11 20:00:10'
  6. GROUP BY host;
  1. +-------------------+-------+
  2. | p95_latency       | host  |
  3. +-------------------+-------+
  4. | 4164.999999999999 | host1 |
  5. |               115 | host2 |
  6. +-------------------+-------+
  7. 2 rows in set (0.11 sec)

Range query

你可以使用 range query来实时监控延迟。例如，按 5 秒窗口计算请求的 p95 延迟：

  1. SELECT 
  2.   ts, 
  3.   host, 
  4.   approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency
  5. FROM 
  6.   grpc_latencies
  7. ALIGN '5s' FILL PREV;
  1. +---------------------+-------+-------------+
  2. | ts                  | host  | p95_latency |
  3. +---------------------+-------+-------------+
  4. | 2024-07-11 20:00:05 | host2 |         114 |
  5. | 2024-07-11 20:00:10 | host2 |         111 |
  6. | 2024-07-11 20:00:15 | host2 |         115 |
  7. | 2024-07-11 20:00:20 | host2 |          95 |
  8. | 2024-07-11 20:00:05 | host1 |       104.5 |
  9. | 2024-07-11 20:00:10 | host1 |        4200 |
  10. | 2024-07-11 20:00:15 | host1 |        3500 |
  11. | 2024-07-11 20:00:20 | host1 |        2500 |
  12. +---------------------+-------+-------------+
  13. 8 rows in set (0.06 sec)

全文搜索

你可以使用 matches 函数来搜索具有 FULLTEXT 索引的列。例如，搜索包含错误信息 timeout 的日志：

  1. SELECT 
  2.   ts,
  3.   api_path,
  4.   log
  5. FROM
  6.   app_logs
  7. WHERE
  8.   matches(log, 'timeout');
  1. +---------------------+------------------+--------------------+
  2. | ts                  | api_path         | log                |
  3. +---------------------+------------------+--------------------+
  4. | 2024-07-11 20:00:10 | /api/v1/billings | Connection timeout |
  5. | 2024-07-11 20:00:10 | /api/v1/resource | Connection timeout |
  6. +---------------------+------------------+--------------------+
  7. 2 rows in set (0.01 sec)

指标和日志的关联查询

通过组合两个表的数据，你可以快速地确定故障时间和相应的日志。以下 SQL 查询使用 JOIN 操作关联指标和日志：

  1. WITH
  2.   metrics AS (
  3.     SELECT 
  4.       ts, 
  5.       host, 
  6.       approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency 
  7.     FROM 
  8.       grpc_latencies 
  9.     ALIGN '5s' FILL PREV
  10.   ), 
  11.   logs AS (
  12.     SELECT 
  13.       ts, 
  14.       host,
  15.       count(log) RANGE '5s' AS num_errors, 
  16.     FROM
  17.       app_logs 
  18.     WHERE
  19.       log_level = 'ERROR'
  20.     ALIGN '5s'
  21. ) 
  22. --- 关联 metric 和日志 ---
  23. SELECT 
  24.   metrics.ts,
  25.   p95_latency, 
  26.   coalesce(num_errors, 0) as num_errors,
  27.   metrics.host
  28. FROM 
  29.   metrics 
  30.   LEFT JOIN logs ON metrics.host = logs.host 
  31.   AND metrics.ts = logs.ts 
  32. ORDER BY 
  33.   metrics.ts;
  1. +---------------------+-------------+------------+-------+
  2. | ts                  | p95_latency | num_errors | host  |
  3. +---------------------+-------------+------------+-------+
  4. | 2024-07-11 20:00:05 |         114 |          0 | host2 |
  5. | 2024-07-11 20:00:05 |       104.5 |          0 | host1 |
  6. | 2024-07-11 20:00:10 |        4200 |         10 | host1 |
  7. | 2024-07-11 20:00:10 |         111 |          0 | host2 |
  8. | 2024-07-11 20:00:15 |         115 |          0 | host2 |
  9. | 2024-07-11 20:00:15 |        3500 |          4 | host1 |
  10. | 2024-07-11 20:00:20 |         110 |          0 | host2 |
  11. | 2024-07-11 20:00:20 |        2500 |          0 | host1 |
  12. +---------------------+-------------+------------+-------+
  13. 8 rows in set (0.02 sec)

GreptimeDB 控制台

GreptimeDB 提供了一个仪表板用于数据探索和管理。

数据探索

按照安装部分中的说明启动 GreptimeDB 后，你可以通过 HTTP 地址 http://localhost:4000/dashboard 访问控制台。

点击 + 按钮添加一个新的查询，在命令文本中编写你的 SQL 命令，然后点击 Run All。 下方的 SQL 会查询 grpc_latencies 表中的所有数据。

  1. SELECT * FROM grpc_latencies;

然后点击结果面板中的 Chart 按钮来可视化数据。

select gRPC latencies

使用 InfluxDB Line Protocol 导入数据

除了 SQL，GreptimeDB 还支持多种协议，其中最常用之一是 InfluxDB Line Protocol。 在仪表板中点击 Ingest 图标，你可以以 InfluxDB Line Protocol 格式上传数据。

例如，将以下数据粘贴到输入框中：

  1. grpc_metrics,host=host1,method_name=GetUser latency=100,code=0 1720728021000000000
  2. grpc_metrics,host=host2,method_name=GetUser latency=110,code=1 1720728021000000000

然后点击 Write 按钮来导入数据到 grpc_metrics 表。如果改表不存在，将会自动创建该表。

下一步

你现在已经体验了 GreptimeDB 的核心功能。 要进一步探索和利用 GreptimeDB：