Quickwit 日志采集接入指南支持的 Agent 一览与 OpenTelemetry 服务配置【免费下载链接】quickwitCloud-native OSS search engine for observability项目地址: https://gitcode.com/GitHub_Trending/qu/quickwitQuickwit 作为云原生日志搜索引擎原生内置 OpenTelemetry 协议OTLP支持可通过 gRPC 端点直接接收来自 OpenTelemetry Collector 的日志与 trace同时对外提供兼容 HTTP 的 Ingest API能够与 Vector、Fluent Bit、FluentD、Logstash 等主流日志采集 Agent 无缝对接。本文将基于仓库中的 supported-agents.md 展开逐一说明每种 Agent 的接入方式、OTLP 服务的启用与禁用配置并结合源码剖析其底层实现帮助你在几分钟内完成日志采集 → Quickwit 索引 → 搜索的完整链路。支持的采集 Agent 一览Quickwit 对采集 Agent 的兼容性分为两条技术路线覆盖了当前可观测性生态中的主流方案Agent接入方式支持程度备注OpenTelemetry CollectorOTLP gRPC/opentelemetry.proto.collector.logs.v1.LogsService原生支持日志默认落入otel-logs-v0_x索引索引自动创建VectorHTTP Ingest API/api/v1/{index_id}/ingest已测试官方提供 syslog → OTLP 数据模型的 remap 配置示例Fluent BitHTTP Ingest API已测试支持json_lines编码Json_date_key映射时间戳FluentDHTTP Ingest API教程即将推出已确认可兼容Logstash仅 HTTP output 且限jsonformat部分支持不支持 Elasticsearch output无法使用其 ES 插件协议所有 HTTP 系 Agent 的通用前提是Quickwit 的 Ingest API 接收 JSON 格式日志并部分兼容 Elasticsearch_bulkAPI因此大多数现有 Agent 很可能无需改造即可接入。这是文档中明确给出的兼容性判断依据实际使用时建议以 rest-api.md 中的 Ingest API 文档为准。接入 OpenTelemetry AgentOTEL CollectorOpenTelemetry Collector 是 Quickwit 官方最推荐的日志采集 Agent两者通过 OTLP gRPC 协议通信链路最短、损耗最低。前置条件启用 Quickwit OpenTelemetry 服务在使用 OTEL Collector 之前必须先确认 Quickwit 的 OpenTelemetry 服务处于启用状态。该服务默认开启启动后 Quickwit 即监听 gRPC 端口默认7281接收 OTLP 请求。验证方式参见 otel-service.md。DaemonSet 模式配置示例Kubernetes文档给出了一个面向 Kubernetes 集群的 OTEL Collector 配置Helm values 形式核心是定义一个指向 Quickwit indexer 的 OTLP exportermode: daemonset presets: logsCollection: enabled: true kubernetesAttributes: enabled: true config: exporters: otlp: # Replace quickwit-host with the hostname of your Quickwit node/service. # On k8s, it should be of the form {quickwit-indexer-service-name}.{namespace}.svc.cluster.local:7281 endpoint: quickwit-host:7281 tls: insecure: true service: pipelines: logs: exporters: - otlp配置要点说明mode: daemonset每个 K8s 节点运行一个 Collector 实例与logsCollection预设配合自动采集节点上的容器日志presets.kubernetesAttributes为每条日志附加k8s.*资源属性如resource_attributes.k8s.container.name便于按 Pod、命名空间、容器维度检索exporters.otlp.endpoint在 K8s 内应填写 Quickwit indexer 的 Service 全限定域名形如{indexer-service}.{namespace}.svc.cluster.local:7281其中7281即 gRPC 端口tls.insecure: trueQuickwit 默认未配置 TLS内网环境下必须关闭 TLS 校验。完整的端到端部署含 Helm 安装 Quickwit 与 OTEL Collector、kubectl port-forward访问 UI、清理步骤可参考 using-otel-collector-with-helm.md其中还给出了可直接复用的otel-values.yaml与索引验证命令。本地快速验证若你想在本机快速验证 OTEL Collector 接入可参照 using-otel-collector.md 的流程启动 Quickwit./quickwit run以 Docker 启动 Collector 并挂载上述配置Linux 下建议--networkhostMac/Windows 下使用host.docker.internal:7281作为 endpoint通过curl向 Collector 的 HTTP 接收端4318端口发送一条 OTLP JSON 日志curl -XPOST http://localhost:4318/v1/logs -H Content-Type: application/json \ --data-binary - EOF { resource_logs: [ { resource: { attributes: [ { key: service.name, value: { stringValue: test-with-curl } } ] }, scope_logs: [ { scope: { name: manual-test }, log_records: [ { time_unix_nano: 1678974011000000000, observed_time_unix_nano: 1678974011000000000, name: test, severity_text: INFO } ] } ] } ] } EOFQuickwit 服务端日志中会出现类似new-split split_id... partition_id...的信息表示已收到日志并创建了新 split等待 split 发布publish后再执行搜索即可看到数据。接入 HTTP 系 Agent除 OTEL Collector 外Quickwit 还通过 Ingest API 接纳各类 HTTP 系 Agent。Ingest 端点为POST /api/v1/{index_id}/ingest任何能发送 JSON 的 Agent 均可接入。VectorVector 的优势在于强大的数据转换能力。由于 Vector 本身不直接生成 OpenTelemetry 格式日志官方教程 using-vector.md 展示了如何用remap将syslog格式映射为 OTLP 数据模型[sources.generate_syslog] type demo_logs format syslog count 100000 interval 0.001 [transforms.remap_syslog] inputs [ generate_syslog] type remap source structured parse_syslog!(.message) .timestamp_nanos to_unix_timestamp!(structured.timestamp, unit: nanoseconds) .body structured .service_name structured.appname .resource_attributes.source_type .source_type .resource_attributes.host.hostname structured.hostname .resource_attributes.service.name structured.appname .attributes.syslog.procid structured.procid .attributes.syslog.facility structured.facility .attributes.syslog.version structured.version .severity_text if includes([emerg, err, crit, alert], structured.severity) { ERROR } else if structured.severity warning { WARN } else if structured.severity debug { DEBUG } else if includes([info, notice], structured.severity) { INFO } else { structured.severity } .scope_name structured.msgid del(.message) del(.timestamp) del(.service) del(.source_type) [sinks.quickwit_logs] type http method post inputs [remap_syslog] encoding.codec json framing.method newline_delimited uri http://127.0.0.1:7280/api/v1/otel-logs-v0_7/ingest这个配置的价值在于通过字段级映射把 Vector 采集到的任意格式日志转换成与otel-logs-v0_x索引 doc mapping 完全吻合的文档结构从而直接复用 Quickwit 内置的 OTLP 日志索引无需预先手工建索引。对应配置文件可参考仓库中的 config/tutorials/vector-otel-logs/vector.toml。接入后即可搜索与聚合例如按分钟统计各severity_text的数量curl -XPOST -H Content-Type: application/json \ http://127.0.0.1:7280/api/v1/otel-logs-v0_7/search \ --data aggregation-query.json聚合查询体histogram按timestamp_nanos以 60000000 微秒即 1 分钟为间隔内嵌terms分组统计 severity{ query: *, max_hits: 0, aggs: { count_per_minute: { histogram: { field: timestamp_nanos, interval: 60000000 }, aggs: { severity_text_count: { terms: { field: severity_text } } } } } }Fluent BitFluent Bit 通过httpoutput 插件直接向 Ingest API 推送日志。教程 using-fluentbit.md 使用了一个仅含timestamp字段的 dynamic 模式索引其余字段由 Quickwit 自动映射version: 0.7 index_id: fluentbit-logs doc_mapping: mode: dynamic field_mappings: - name: timestamp type: datetime input_formats: - unix_timestamp output_format: unix_timestamp_secs fast: true timestamp_field: timestamp indexing_settings: commit_timeout_secs: 10对应的 Fluent Bit 配置[INPUT] Name dummy Tag dummy.log [OUTPUT] Name http Match * URI /api/v1/fluentbit-logs/ingest Host localhost Port 7280 tls Off Format json_lines Json_date_key timestamp Json_date_format epoch关键点Json_date_key与索引中的timestamp字段对应Json_date_format epoch保证时间戳以 unix 时间写入从而被datetime字段正确解析。该示例索引配置完整版见 config/tutorials/fluentbit-logs/index-config.yaml。FluentD 与 LogstashFluentD与 Fluent Bit 类似走 HTTP 路线官方教程coming soon但接入原理一致HTTP output JSONLogstashQuickwit 不支持其 Elasticsearch output 插件但可使用 HTTP output 插件且format必须为json不能使用json_batch等其他格式。这是文档明确标注的唯一约束。OpenTelemetry 服务OTLP gRPC 端点详解默认行为Quickwit 原生支持 OpenTelemetry ProtocolOTLP默认启动一个 gRPC 服务端口7281用于接收来自 OTEL Collector 的日志与 trace。日志默认写入otel-logs-v0_x索引trace 默认写入otel-trace-v0_x索引若索引不存在Quickwit 会自动创建无需人工干预。两个索引的 doc mapping 均可在 otel-service.md 中查阅。版本提示仓库文档如 otel-service.md中记录的默认索引名为otel-logs-v0_7而当前源码常量已演进为otel-logs-v0_9见下文源码分析说明该索引名随 Quickwit 版本迭代。实操时请以你所安装版本实际生成的索引名为准例如在 UI 的索引列表中确认。关闭 OTLP 端点若出于安全或资源考量需要关闭该端点文档给出两种等价方式环境变量方式启动 Quickwit 时设置QW_ENABLE_OTLP_ENDPOINTfalse配置文件方式在 node config 中设置 indexer 配置项enable_otlp_endpoint: false# ... Indexer configuration ... indexer: enable_otlp_endpoint: false完整的 node config 字段说明参见 node-config.md。将日志路由到自定义索引默认情况下所有 OTLP 日志都写入otel-logs-v0_x。如果希望把日志发送到你自己创建的索引只需在 gRPC 请求的 metadata 中设置请求头qw-otel-logs-index: 目标索引 ID同理trace 请求头为qw-otel-traces-index。在 OTEL Collector 配置中可通过 exporter 的headers声明相关示例见 using-otel-collector.md 中注释掉的配置块。也可以绕过 Collector直接调用 Ingest API 写入该索引。源码级实现印证文档描述的各项能力在仓库源码中均有对应实现可帮助你从协议接入层面进一步理解其原理gRPC 服务注册在 quickwit-serve/src/grpc.rs 中OTLP trace 与 log 服务分别在enabled_grpc_services中登记为otlp-traces与otlp-logs其中 logs 服务挂载的是LogsServiceServer实现opentelemetry.proto.collector.logs.v1.LogsService。启动日志中的enabled_grpc_services{otlp-log, otlp-trace}即来自此处可在 using-otel-collector-with-helm.md 的部署输出中看到。日志数据模型与索引常量quickwit-opentelemetry/src/otlp/logs.rs 中定义了OTEL_LOGS_INDEX_ID常量与内置索引配置doc mapping 采用strict模式核心字段包括timestamp_nanosdatetimeunix_timestamp_nanos输出、service_nametextrawtokenizer fast、bodyjson、attributes/resource_attributesjsonraw、trace_id/span_idbytes hex、severity_text/severity_number等并指定timestamp_field: timestamp_nanos。该配置与文档中的 YAML 完全一致即开箱即用索引的来源。自定义索引请求头解析quickwit-opentelemetry/src/otlp/mod.rs 定义了信号到请求头的映射Logs → qw-otel-logs-index、Traces → qw-otel-traces-indexextract_otel_index_id_from_metadata 从 gRPC metadata 中读取请求头并做 index ID 合法性校验未设置时回落到default_index_id()。同文件底部还包含对多值、空白值等异常请求头的单元测试印证了校验逻辑。已知限制与注意事项基于 otel-service.md 中记录的约束接入时需注意OTLP HTTP 传输仅支持 Binary Protobuf 编码JSON 编码暂未支持——因此教程中使用curl发送的 JSON 测试请求实际是发给 Collector 的 HTTP 接收端4318Collector 到 Quickwit 之间走的是 gRPC采集链路整体可用但如需 High-Durability高持久化语义需要关注所安装版本的 Ingest API 能力说明使用dynamic模式索引如 Fluent Bit 示例时未在 doc mapping 中声明的字段会自动被索引若使用strict模式如otel-logs-v0_x则文档必须与 mapping 严格匹配字段名请严格参照数据模型一节。小结Quickwit 通过OTLP gRPC 原生接入 HTTP Ingest API 兼容双通道覆盖了当前主流的日志采集 Agent生产环境推荐使用 OTEL Collector 走 OTLP 直连以获得最小链路与内置索引已有 Agent 体系Vector、Fluent Bit、FluentD、Logstash则可零改造或仅做格式映射后通过 HTTP 接入。无论哪种方式接入后都可以直接使用 Quickwit 的 UI 与 REST API 进行全文检索、聚合分析与告警对接。【免费下载链接】quickwitCloud-native OSS search engine for observability项目地址: https://gitcode.com/GitHub_Trending/qu/quickwit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考