gliderlabs/logspout

logspout

![CircleCI]([] ![IRC Channel]([]

Docker Hub上的自动构建gliderlabs/logspout:latest和progrium/logspout:latest现在指向release分支。对于master分支，请使用gliderlabs/logspout:master。各个版本也可在https://github.com/gliderlabs/logspout/releases%E4%BD%9C%E4%B8%BA%E4%BF%9D%E5%AD%98%E7%9A%84%E9%95%9C%E5%83%8F%E8%8E%B7%E5%8F%96%E3%80%82

Logspout是一个运行在Docker内部的Docker容器日志路由器。它附加到主机上的所有容器，然后将它们的日志路由到您指定的任何位置。它还具有可扩展的模块系统。

它是一个基本无状态的日志工具。它不用于管理日志文件或查看历史记录，仅用于将日志传输到它们应存的其他位置。

目前它仅捕获stdout和stderr，但计划添加收集容器syslog的模块。

获取logspout

Logspout是一个非常小的Docker容器（虚拟大小15.2MB，基于https://github.com/gliderlabs/docker-alpine%EF%BC%89%E3%80%82%E4%BB%8E%E7%B4%A2%E5%BC%95%E6%8B%89%E5%8F%96%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC%EF%BC%9A

bash
$ docker pull gliderlabs/logspout:latest

您也可以下载并加载特定版本：

bash
$ curl -s dl.gliderlabs.com/logspout/v2.tgz | docker load

使用logspout

路由所有容器输出到远程syslog

使用logspout最简单的方法是将所有日志发送到远程syslog。只需将syslog URI（或多个逗号分隔的URI）作为命令传递。这里我们展示在URI中使用tls加密传输选项。此外，我们始终使用-v将Docker Unix套接字挂载到/var/run/docker.sock：

bash
$ docker run --name="logspout" \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \
    syslog+tls://logs.papertrailapp.com:55555

logspout将收集未使用-t选项启动且配置了与docker logs兼容的日志驱动程序（journald和json-file）的其他容器的日志。

要了解syslog消息使用哪些数据，请参阅http://github.com/gliderlabs/logspout/blob/master/adapters%E6%96%87%E6%A1%A3%E3%80%82

容器必须能够访问Docker Unix套接字才能挂载它。当启用命名空间重映射时，这通常会成为问题。要为logspout容器禁用重映射，请在docker run、docker create等命令中传递--userns=host标志。

忽略特定容器

您可以通过在启动容器时设置环境变量来告诉logspout忽略特定容器，如下所示：

bash
$ docker run -d -e 'LOGSPOUT=ignore' image

或者，通过添加您在运行logspout时通过设置环境变量定义的标签：

bash
$ docker run --name="logspout" \
    -e EXCLUDE_LABEL=logspout.exclude \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout
$ docker run -d --label logspout.exclude=true image

Logspout还允许通过环境变量EXCLUDE_LABELS或EXCLUDE_LABEL指定标签列表（使用;作为分隔符）来忽略容器：

bash
$ docker run --name="logspout" \
    -e EXCLUDE_LABELS=k8s:app;backend:rails;io.kubernetes.pod.namespace:default \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout
$ docker run -d --label k8s=app image1
$ docker run -d --label backend=rails image2

注意 设置EXCLUDE_LABELS将优先于EXCLUDE_LABEL。

包含特定容器

您可以通过在URI上设置过滤参数来告诉logspout仅包含某些容器：

bash
$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \
    raw://192.168.10.10:5000?filter.name=*_db

$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \
    raw://192.168.10.10:5000?filter.id=3b6ba57db54a

$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \
    raw://192.168.10.10:5000?filter.sources=stdout%2Cstderr

# 转发同时具有标签'a'以'x'开头和标签'b'以'y'结尾的容器的日志
$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \
    raw://192.168.10.10:5000?filter.labels=a:x*%2Cb:*y

注意，您必须对参数值进行URL编码，例如filter.sources和filter.labels中的逗号。

多日志目的地

您可以通过逗号分隔URI来路由到多个目的地：

bash
$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \
    raw://192.168.10.10:5000?filter.name=*_db,syslog+tls://logs.papertrailapp.com:55555?filter.name=*_app

抑制回溯日志

您可以通过设置BACKLOG=false环境变量告诉logspout仅显示自容器"启动"或"重启"事件以来的日志条目（相当于docker logs --since=0s）：

bash
$ docker run -d --name="logspout" \
    -e 'BACKLOG=false' \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout

默认行为是输出自容器创建以来的所有日志（相当于docker logs --tail=all或简单的docker logs）。

注意：使用此选项可能导致容器启动后丢失前几行日志输出，如果容器在logspout有机会看到日志之前就开始输出日志。如果您的应用程序必须确保捕获每一行日志，建议彻底测试和/或避免使用此选项（代价是为每个重启的容器获取完整的回溯日志）。这不会影响已删除并重新创建的容器。

环境变量TAIL

虽然BACKLOG=false通过将Docker Logs.Options.Since设置为time.Now()来限制尾部日志，但另一种限制尾部日志的机制是设置TAIL=n。使用此机制可以避免解析日志文件的早期内容，如果尾部内容无关紧要或已损坏，这可能具有速度优势。

使用curl检查日志流

使用http://github.com/gliderlabs/logspout/blob/master/httpstream%EF%BC%8C%E6%82%A8%E5%8F%AF%E4%BB%A5%E4%BD%BF%E7%94%A8curl%E8%BF%9E%E6%8E%A5%E5%AE%9E%E6%97%B6%E6%9F%A5%E7%9C%8B%E6%9C%AC%E5%9C%B0%E8%81%9A%E5%90%88%E6%97%A5%E5%BF%97%E3%80%82%E6%97%A0%E9%9C%80%E8%AE%BE%E7%BD%AE%E8%B7%AF%E7%94%B1URI%E5%8D%B3%E5%8F%AF%E6%89%A7%E8%A1%8C%E6%AD%A4%E6%93%8D%E4%BD%9C%E3%80%82

bash
$ docker run -d --name="logspout" \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    --publish=127.0.0.1:8000:80 \
    gliderlabs/logspout
$ curl http://127.0.0.1:8000/logs

您应该会看到所有容器日志的彩色流。您可以按容器名称等进行过滤。您还可以获取JSON对象，或升级到WebSocket在浏览器中获取JSON日志。

有关所有选项，请参见http://github.com/gliderlabs/logspout/blob/master/httpstream%E3%80%82

通过HTTP创建自定义路由

使用http://github.com/gliderlabs/logspout/blob/master/routesapi%EF%BC%8Clogspout%E8%BF%98%E5%8F%AF%E4%BB%A5%E5%85%AC%E5%BC%80%60/routes%60%E8%B5%84%E6%BA%90%E6%9D%A5%E5%88%9B%E5%BB%BA%E5%92%8C%E7%AE%A1%E7%90%86%E8%B7%AF%E7%94%B1%E3%80%82

bash
$ curl $(docker port `docker ps -lq` 8000)/routes \
    -X POST \
    -d '{"source": {"filter": "db", "types": ["stderr"]}, "target": {"type": "syslog", "addr": "logs.papertrailapp.com:55555"}}'

此示例创建一个新的syslog路由到Papertrail，仅包含名称中带有db的容器的stderr日志。

路由存储在磁盘上，因此默认情况下路由是临时的。您可以挂载卷到/mnt/routes以持久化它们。

有关所有选项，请参见http://github.com/gliderlabs/logspout/blob/master/routesapi%E3%80%82

检测Docker日志流超时

Logspout依赖Docker API来检索容器日志。API故障可能导致日志流挂起。Logspout可以检测并重启非活动的Docker日志流。使用环境变量INACTIVITY_TIMEOUT启用此功能。例如：INACTIVITY_TIMEOUT=1m设置1分钟阈值。

多行日志

要启用多行日志，必须首先在适配器前加上multiline适配器：

bash
$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \
    multiline+raw://192.168.10.10:5000?filter.name=*_db

使用上述前缀默认对所有容器启用多行日志。要仅对特定容器启用，为logspout设置MULTILINE_ENABLE_DEFAULT=false，并在被监控的容器上使用LOGSPOUT_MULTILINE环境变量：

bash
$ docker run -d -e 'LOGSPOUT_MULTILINE=true' image

MULTILINE_MATCH

使用环境变量MULTILINE_MATCH=<first|last|nonfirst|nonlast>（默认nonfirst）定义应将哪些行与MULTILINE_PATTERN匹配。

• first：仅匹配第一行，并附加后续消息直到匹配另一行
• last：连接所有消息直到模式匹配下一行
• nonlast：匹配一行，附加即将到来的匹配行，也附加第一个非匹配行并开始
• nonfirst：将所有匹配行附加到第一行，并从下一个非匹配行重新开始

重要！

如果将多行日志与raw一起使用，建议对Data进行json编码以避免输出中的换行，例如：

"RAW_FORMAT={{ toJSON .Data }}\n"

环境变量

• ALLOW_TTY - 包含使用-t或--tty（即"分配伪TTY"）启动的容器的日志
• BACKLOG - 抑制容器尾部回溯日志
• TAIL - 指定logspout启动时捕获的日志尾部行数（默认all）
• DEBUG - 输出调试日志
• EXCLUDE_LABEL - 排除具有特定标签的容器。标签值可以是true或通过在标签名称后使用:指定的自定义值，如label_name:label_value
• INACTIVITY_TIMEOUT - 检测Docker API挂起（默认0）
• HTTP_BIND_ADDRESS - 配置监听的接口地址（默认0.0.0.0）
• PORT或HTTP_PORT - 配置监听端口（默认80）
• RAW_FORMAT - raw适配器的日志格式（默认{{.Data}}\n）
• RETRY_COUNT - 断开的套接字重试次数（默认10）
• ROUTESPATH - 路由路径（默认/mnt/routes）
• SYSLOG_DATA - 数据字段的数据（默认{{.Data}}）
• SYSLOG_FORMAT - 输出的syslog格式，rfc3164或rfc5424（默认rfc5424）
• SYSLOG_HOSTNAME - 主机名字段的数据（默认{{.Container.Config.Hostname}}）
• SYSLOG_PID - PID字段的数据（默认{{.Container.State.Pid}}）
• SYSLOG_PRIORITY - 优先级字段的数据（默认{{.Priority}}）
• SYSLOG_STRUCTURED_DATA - 结构化数据字段的数据
• SYSLOG_TAG - 标签字段的数据（默认{{.ContainerName}}+route.Options["append_tag"]）
• SYSLOG_TCP_FRAMING - 对于TCP或TLS传输，是否在输出消息中使用octet-counted帧或traditional LF帧（默认traditional）
• SYSLOG_TIMESTAMP - 时间戳字段的数据（默认{{.Timestamp}}）
• MULTILINE_ENABLE_DEFAULT - 使用multiline适配器时对所有容器启用多行日志（默认true）
• MULTILINE_MATCH - 确定模式应匹配哪些行，first|last|nonfirst|nonlast之一，详情见：MULTILINE_MATCH（默认nonfirst）
• MULTILINE_PATTERN - 多行日志的模式，见：MULTILINE_MATCH（默认：^\s）
• MULTILINE_FLUSH_AFTER - 多行日志条目中第一行和最后一行之间的最大时间（毫秒）（默认：500）
• MULTILINE_SEPARATOR - 输出行之间的分隔符（默认：\n）

Raw格式

raw适配器有一个toJSON函数，可用于格式化消息/字段以简单方式生成类JSON输出或完整JSON输出。

RAW_FORMAT环境变量用作Go模板，并将https://github.com/gliderlabs/logspout/blob/master/router/types.go#L52%E4%BD%9C%E4%B8%BA%E6%95%B0%E6%8D%AE%E4%BC%A0%E9%80%92%E3%80%82%E6%82%A8%E5%8F%AF%E4%BB%A5%E8%AE%BF%E9%97%AE%E4%BB%A5%E4%B8%8B%E5%AD%97%E6%AE%B5%EF%BC%9A

• Source - 源流名称（"stdout"、"stderr"等）
• Data - 原始日志消息
• Time - Go Time结构体
• Container - https://github.com/fsouza/go-dockerclient%E7%9A%84%60Container%60%E7%BB%93%E6%9E%84%E4%BD%93%EF%BC%88%E5%8F%82%E8%A7%81https://github.com/fsouza/go-dockerclient/blob/master/container.go#L443%E6%BA%90%E6%96%87%E4%BB%B6%E4%BA%86%E8%A7%A3%E5%8F%AF%E8%AE%BF%E9%97%AE%E5%AD%97%E6%AE%B5%EF%BC%89

使用示例

混合JSON + 通用格式：

{{ .Time.Format "2006-01-02T15:04:05Z07:00" }} { "container" : "{{ .Container.Name }}", "labels": {{ toJSON .Container.Config.Labels }}, "timestamp": "{{ .Time.Format "2006-01-02T15:04:05Z07:00" }}", "source" : "{{ .Source }}", "message": {{ toJSON .Data }} }

输出示例：

2017-10-26T11:59:32Z { "container" : "/catalogo_worker_1", "image": "sha256:e9bce6c17c80c603c4c8dbac2ad2285982d218f6ea0332f8b0fb84572941b773", "labels": {"com.docker.compose.config-hash":"4f9c3d3bfb2f65e29a4bc8a4a1b3f0a1c8a42323106a5e9106fe9279f8031321","com.docker.compose.container-number":"1","com.docker.compose.oneoff":"False","com.docker.compose.project":"catalogo","com.docker.compose.service":"worker","com.docker.compose.version":"1.16.1","logging":"true"}, "timestamp": "2017-10-26T11:59:32Z", "source" : "stdout", "message": "2017-10-26 11:59:32,950 INFO success: command_bus_0 entered RUNNING state, process has stayed up for \u003e than 1 seconds (startsecs)" }

完整JSON格式：

{ "container" : "{{ .Container.Name }}", "labels