菜单
文档breadcrumb arrow Grafana Lokibreadcrumb arrow 开始使用breadcrumb arrow 标签breadcrumb arrow 结构化元数据
开源

什么是结构化元数据

警告

结构化元数据已添加到块格式 V4 中，当 schema 版本大于或等于 13 时使用此格式。请参阅 Schema 配置 了解有关 schema 版本的更多详情。

选择恰当的、低基数的标签对于有效运行和查询 Loki 至关重要。有些元数据，特别是与基础设施相关的元数据，很难嵌入到日志行中，而且基数过高，无法作为索引标签有效存储（从而降低索引性能）。

结构化元数据是一种将元数据附加到日志的方式，而无需对其进行索引或将其包含在日志行内容本身中。有用的元数据示例包括 Kubernetes Pod 名称、进程 ID 或任何其他经常在查询中使用但基数较高且在查询时提取成本高昂的标签。

结构化元数据还可用于从日志行中查询常用元数据，而无需在查询时应用解析器。例如，大型 JSON blob 或使用复杂正则表达式模式编写的低效查询会带来高昂的性能成本。有用的元数据示例包括 container_IDs 或用户 ID。

何时使用结构化元数据

您应仅在以下情况中使用结构化元数据

  • 如果您使用 Grafana Alloy 或 OpenTelemetry Collector 并以 OpenTelemetry 格式摄取数据。结构化元数据旨在支持原生摄取 OpenTelemetry 数据。
  • 如果您有不应作为标签使用且日志行中不存在的高基数元数据。例如可能包括 process_id 或 thread_id 或 Kubernetes Pod 名称。
  • 如果您正在使用 日志钻取 来可视化和探索您的 Loki 日志。您必须在 Loki 配置中将 discover_log_levels 和 allow_structured_metadata 设置为 true。
  • 如果您是每月摄取超过 75TB 日志的大型客户，并且正在使用 布隆过滤器（实验性），从 Loki 3.3 开始，布隆过滤器现在利用结构化元数据。

启用或禁用结构化元数据

您可以在 Loki 的 config.yaml 文件中启用结构化元数据。

yaml 
limits_config:
    allow_structured_metadata: true
    volume_enabled: true
    retention_period: 672h # 28 days retention

您可以通过在 limits_config 部分设置 allow_structured_metadata: false 或设置命令行参数 -validation.allow-structured-metadata=false 来禁用结构化元数据。请注意，支持摄取 OTLP 数据需要结构化元数据。

将结构化元数据附加到日志行

您可以选择在推送 payload 中将结构化元数据与每条日志行和时间戳一起附加到日志行。有关如何通过 HTTP 端点将日志推送到 Loki 的更多信息，请参阅 HTTP API 文档。

或者，您可以使用 Grafana Alloy 或 Promtail 提取结构化元数据并将其附加到您的日志行。有关更多信息，请参阅 Promtail：结构化元数据阶段。

从 Loki 1.2.0 版本开始，Logstash 输出插件已添加对结构化元数据的支持。有关更多信息，请参阅 Logstash。

警告

结构化元数据的大小在断言摄取速率限制时会考虑在内。此外，对于每条日志行可以附加多少结构化元数据也有单独的限制。

yaml 
# Maximum size accepted for structured metadata per log line.
# CLI flag: -limits.max-structured-metadata-size
[max_structured_metadata_size: <int> | default = 64KB]

# Maximum number of structured metadata entries per log line.
# CLI flag: -limits.max-structured-metadata-entries-count
[max_structured_metadata_entries_count: <int> | default = 128]

查询结构化元数据

结构化元数据会自动为每条返回的日志行提取，并添加到查询返回的标签中。您可以使用结构化元数据的标签，通过 标签过滤表达式 过滤日志行。

例如，如果您有一些日志行附加了名为 pod 的结构化元数据标签，则可以使用以下方式过滤日志行

logql 
{job="example"} | pod="myservice-abc1234-56789"

当然，您可以同时按多个结构化元数据标签进行过滤

logql 
{job="example"} | pod="myservice-abc1234-56789" | trace_id="0242ac120002"

请注意，由于结构化元数据会自动提取到结果标签中，某些指标查询可能会返回诸如 maximum of series (50000) reached for a single query 的错误。您可以使用 Keep 和 Drop 阶段过滤掉不需要的标签。例如

logql 
count_over_time({job="example"} | trace_id="0242ac120002" | keep job  [5m])