datadog/dogstatsd-socat-proxy

DogStatsD UDP到Unix Domain Socket代理镜像文档

1. 镜像概述和主要用途

本Docker镜像基于socat实现UDP到Unix Domain Socket（UDS）的代理功能，旨在帮助客户端库暂未支持UDS协议的场景下，实现向UDS协议的过渡。镜像设计为应用的sidecar容器运行，接收发送至localhost:8125的UDP数据包，并将其转发至指定的UDS路径（/socket/statsd.socket），从而实现与DogStatsD的通信。

2. 核心功能和特性

• 协议转发：将发送至localhost:8125（UDP协议）的数据包转发至Unix Domain Socket（/socket/statsd.socket）。
• 轻量级实现：基于socat工具，组件轻量，资源占用低。
• Sidecar部署：专为作为应用的sidecar容器设计，与主应用容器协同运行，无需修改主应用配置即可实现协议过渡。

3. 使用场景和适用范围

适用于客户端应用需向DogStatsD发送指标数据，但客户端库暂不支持Unix Domain Socket（UDS）协议的场景。作为临时过渡方案，帮助用户在不升级客户端库的情况下，通过UDP协议间接使用UDS通信能力。

4. 使用方法和配置说明

4.1 基本运行要求

• 挂载UDS路径：需将DogStatsD的Unix Domain Socket路径挂载至容器内的/socket/statsd.socket（通常通过-v参数实现）。
• 重启策略：必须配置--restart=always（Docker）或等效的自动重启策略（如Kubernetes的restartPolicy），因socat在写入错误时会退出，需确保容器自动重启以恢复服务。

4.2 Docker运行命令

直接使用Docker运行时，需指定挂载卷、端口映射及重启策略，示例命令如下：

bash
docker run -d \
  --name dogstatsd-socat-proxy \
  --restart=always \
  -p 8125:8125/udp \
  -v /var/run/datadog/:/socket:ro \  # 挂载主机DogStatsD socket路径至容器/socket
  datadog/dogstatsd-socat-proxy:beta

参数说明：

• -p 8125:8125/udp：映射UDP端口8125，接收客户端发送的UDP数据包。
• -v /var/run/datadog/:/socket:ro：只读挂载主机上的DogStatsD socket目录至容器/socket，确保容器可访问/socket/statsd.socket。
• --restart=always：容器退出时自动重启，避免因socat写入错误导致服务中断。

4.3 Kubernetes部署示例

在Kubernetes集群中，本镜像通常作为sidecar容器与业务容器部署在同一Pod内。以下是Deployment配置示例：

yaml
apiVersion: apps/v1  # 注意：原示例使用extensions/v1beta1，已废弃，此处更新为当前稳定版本apps/v1
kind: Deployment
metadata:
  name: test-producer
spec:
  replicas: 1
  selector:
    matchLabels:
      app: test-producer
  template:
    metadata:
      labels:
        app: test-producer
    spec:
      containers:
        # 1. 业务容器（需替换为实际业务容器配置）
        - name: [业务容器名称]
          image: [业务容器镜像]
          # ... 其他业务容器配置（如环境变量、资源限制等）

        # 2. DogStatsD代理sidecar容器
        - name: socat-proxy
          image: datadog/dogstatsd-socat-proxy:beta
          ports:
            - containerPort: 8125
              name: dogstatsdport
              protocol: UDP  # 仅支持UDP协议
          volumeMounts:
            - name: dsdsocket
              mountPath: /socket  # 挂载DogStatsD socket目录至容器内/socket
      volumes:
        # 定义DogStatsD socket存储卷（根据实际环境调整hostPath路径）
        - name: dsdsocket
          hostPath:
            path: /var/run/dogstatsd  # 主机上DogStatsD socket所在路径
            type: Directory  # 确保路径为目录

配置说明：

• volumes：通过hostPath挂载主机上的DogStatsD socket目录（通常为/var/run/dogstatsd）。
• volumeMounts：将上述卷挂载至sidecar容器的/socket目录，使容器可访问/socket/statsd.socket。
• 业务容器需将指标数据发送至localhost:8125（同一Pod内的sidecar容器地址），由sidecar转发至UDS。

5. 注意事项

• 数据包丢失风险：socat在遇到写入错误（如UDS不可用）时会主动退出，容器重启期间发送至localhost:8125的UDP数据包将丢失。
• 依赖DogStatsD服务：需确保主机或集群中已运行DogStatsD服务，且其Unix Domain Socket路径正确挂载至容器/socket/statsd.socket。

6. 声明

该镜像对应的代码仓库已被弃用（deprecated），建议评估并迁移至官方支持的客户端库或替代方案。