可观测性

使用 GitLab 可观测性（O11y）可以：

• 通过统一的可观测性仪表板监控应用程序性能。
• 在单一平台上查看分布式跟踪、日志和指标。
• 识别并排查应用程序中的性能瓶颈。

概览请参见 GitLab 实验性可观测性（O11y）介绍。

加入关于如何有趣地使用 GitLab O11y 的讨论，请访问 GitLab O11y Discord 频道。

为何选择 GitLab 可观测性

• 成本效益高的开源模式：只需支付计算资源费用，而非按座位许可，使任何规模的团队都能负担得起可观测性。可直接贡献功能和修复，帮助确保平台发展以满足您的特定需求。
• 简化的访问管理：新工程师获得代码仓库访问权限时，会自动获得生产可观测性数据的访问权，有助于消除冗长的配置流程。这种统一访问模型确保团队成员无需行政延迟即可立即参与故障排除和监控工作。
• 增强的开发工作流：开发者可将代码变更与应用程序性能指标直接关联，更易识别部署何时引入问题。代码提交与运行时行为之间的紧密集成加速了调试过程，缩短了平均解决时间。
• 左移可观测性：通过将可观测性数据整合到开发过程中，团队能够在开发周期早期发现性能问题和异常。这种主动方法降低了修复问题的成本和影响。开源特性使得编排全面模拟生产环境的暂存环境更加容易且更具成本效益。
• 精简的事件响应：发生问题时，团队能更快了解最近的部署、代码变更及涉及的开发者，有助于更快进行分类和处理。这种集成提供了代码和运营数据的单一视图。
• 决策旁的数据：实时性能指标和用户行为数据可在开发环境中获取，帮助团队就功能优先级、技术债务和优化工作做出明智决策。
• 合规性与审计追踪：集成创建了全面的审计追踪，将代码变更与系统行为关联起来，这对合规要求和事后分析很有价值。
• 减少工具切换：开发团队无需离开熟悉的 GitLab 环境即可访问监控数据、警报和性能洞察，有助于提高生产力并降低认知负荷。

设置 GitLab 可观测性实例

可观测性数据在一个独立的应用程序中收集，位于你的 GitLab.com 实例之外。GitLab 实例的问题不会影响可观测性数据的收集或查看，反之亦然。

前提条件：

• 你必须拥有一个 EC2 实例或类似的虚拟机，具备以下条件：
  • 最小配置：t3.large（2 个 vCPU，8GB 内存）。
  • 生产环境推荐：t3.xlarge（4 个 vCPU，16GB 内存）。
  • 至少 100GB 存储空间。
• 必须安装 Docker 和 Docker Compose。
• 你的 GitLab 版本必须是 18.1 或更高版本。
• 你的 GitLab 实例必须连接到可观测性实例。

配置服务器和存储

对于 AWS EC2：

1. 启动一个至少有 2 个 vCPU 和 8GB 内存的 EC2 实例。
2. 添加一个至少 100GB 的 EBS 卷。
3. 使用 SSH 连接到你的实例。

挂载存储卷

sudo mkdir -p /mnt/data
sudo mount /dev/xvdbb /mnt/data  # 将 xvdbb 替换为你的卷名
sudo chown -R $(whoami):$(whoami) /mnt/data

对于永久挂载，添加到 /etc/fstab：

echo '/dev/xvdbb /mnt/data ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab

安装 Docker

对于 Ubuntu/Debian：

sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)

对于 Amazon Linux：

sudo dnf update
sudo dnf install -y docker
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)

退出并重新登录，或运行：

newgrp docker

配置 Docker 使用已挂载的卷

sudo mkdir -p /mnt/data/docker
sudo bash -c 'cat > /etc/docker/daemon.json << EOF
{
  "data-root": "/mnt/data/docker"
}
EOF'
sudo systemctl restart docker

通过以下命令验证：

docker info | grep "Docker Root Dir"

安装 GitLab 可观测性

cd /mnt/data
git clone -b main https://gitlab.com/gitlab-org/embody-team/experimental-observability/gitlab_o11y.git
cd gitlab_o11y/deploy/docker
docker-compose up -d

如果遇到超时错误，请使用：

COMPOSE_HTTP_TIMEOUT=300 docker-compose up -d

可选：使用外部 ClickHouse 数据库

如果你希望，可以使用自己的 ClickHouse 数据库。

前提条件：

• 确保你的外部 ClickHouse 实例可访问且已正确配置所需的认证凭据。

在运行 docker-compose up -d 前，完成以下步骤：

1. 打开 docker-compose.yml 文件。
2. 打开 docker-compose.yml 并注释掉：
   • clickhouse 和 zookeeper 服务。
   • x-clickhouse-defaults 和 x-clickhouse-depend 部分。
3. 在以下文件中，将所有出现的 clickhouse:9000 替换为你的相关 ClickHouse 端点和 TCP 端口（例如 my-clickhouse.example.com:9000）。如果你的 ClickHouse 实例需要认证，你可能还需要更新连接字符串以包含凭证：
   • docker-compose.yml
   • otel-collector-config.yaml
   • prometheus-config.yml

为 GitLab 可观测性配置网络访问

为了正确接收遥测数据，你需要在 GitLab O11y 实例的安全组中开放特定端口：

1. 进入 AWS 控制台 > EC2 > 安全组。
2. 选择附加到你的 GitLab O11y 实例的安全组。
3. 选择 编辑入站规则。
4. 添加以下规则：
   • 类型：自定义 TCP，端口：8080，来源：你的 IP 或 0.0.0.0/0（用于 UI 访问）
   • 类型：自定义 TCP，端口：4317，来源：你的 IP 或 0.0.0.0/0（用于 OTLP gRPC）
   • 类型：自定义 TCP，端口：4318，来源：你的 IP 或 0.0.0.0/0（用于 OTLP HTTP）
   • 类型：自定义 TCP，端口：9411，来源：你的 IP 或 0.0.0.0/0（用于 Zipkin - 可选）
   • 类型：自定义 TCP，端口：14268，来源：你的 IP 或 0.0.0.0/0（用于 Jaeger HTTP - 可选）
   • 类型：自定义 TCP，端口：14250，来源：你的 IP 或 0.0.0.0/0（用于 Jaeger gRPC - 可选）
5. 选择 保存规则。

访问 GitLab 可观测性

在以下地址访问 GitLab O11y UI：

http://[your-instance-ip]:8080

连接 GitLab 到 GitLab 可观测性

配置 GitLab 并启用功能开关

使用 Rails 控制台为你的组配置 GitLab O11y URL 并启用功能开关：

1. 访问 Rails 控制台：

   Linux 包（Omnibus）

   sudo gitlab-rails console

   Docker

   docker exec -it gitlab gitlab-rails console

2. 为你的组配置可观测性设置并启用功能开关：

   group = Group.find_by_path('your-group-name')
   
   Observability::GroupO11ySetting.create!(
     group_id: group.id,
     o11y_service_url: 'your-o11y-instance-url',
     o11y_service_user_email: '[email protected]',
     o11y_service_password: 'your-secure-password',
     o11y_service_post_message_encryption_key: 'your-super-secret-encryption-key-here-32-chars-minimum'
   )
   
   Feature.enable(:observability_sass_features, group)
   
   Feature.enabled?(:observability_sass_features, group)

   替换：

   • your-group-name 为你的实际组路径
   • your-o11y-instance-url 为你的 GitLab O11y 实例 URL（例如：http://192.168.1.100:8080）
   • 邮箱和密码为你偏好的凭证
   • 加密密钥为一个安全的 32 位以上字符的字符串

   最后一条命令应返回 true 以确认功能已启用。

使用 GitLab 的可观测性功能

配置好 GitLab 可观测性（O11y）后，若要访问嵌入 GitLab 的仪表板：

1. 在左侧边栏中，选择「搜索或前往」并找到已启用该功能的群组。
2. 在左侧边栏中，选择「可观测性」。

如果「可观测性」未显示在左侧边栏， 请直接访问 http://<gitlab_instance>/groups/<group_path>/-/observability/services。

向 GitLab 可观测性发送遥测数据

你可以通过使用 OpenTelemetry SDK 发送样本遥测数据来测试你的 GitLab O11y 安装。此示例使用 Ruby，但 OpenTelemetry 为多种语言提供了 SDK。

先决条件：

• 本地机器上已安装 Ruby

• 所需的 gem 包：

  gem install opentelemetry-sdk opentelemetry-exporter-otlp

创建基本测试脚本

创建一个名为 test_o11y.rb 的文件，内容如下：

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'

OpenTelemetry::SDK.configure do |c|
  # 定义服务信息
  resource = OpenTelemetry::SDK::Resources::Resource.create({
    'service.name' => 'test-service',
    'service.version' => '1.0.0',
    'deployment.environment' => 'production'
  })
  c.resource = resource

  # 配置 OTLP 导出器以发送到 GitLab O11y
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'http://[your-o11y-instance-ip]:4318/v1/traces'
      )
    )
  )
end

# 获取追踪器和创建 span
tracer = OpenTelemetry.tracer_provider.tracer('basic-demo')

# 创建父级 span
tracer.in_span('parent-operation') do |parent|
  parent.set_attribute('custom.attribute', 'test-value')
  puts "创建了父级 span: #{parent.context.hex_span_id}"

  # 创建子级 span
  tracer.in_span('child-operation') do |child|
    child.set_attribute('custom.child', 'child-value')
    puts "创建了子级 span: #{child.context.hex_span_id}"
    sleep(1)
  end
end

puts "等待导出..."
sleep(5)
puts "完成！"

将 [your-o11y-instance-ip] 替换为你的 GitLab O11y 实例的 IP 地址或主机名。

运行测试

1. 运行脚本：

   ruby test_o11y.rb

2. 检查你的 GitLab O11y 仪表板：

   • 打开 http://[your-o11y-instance-ip]:8080
   • 进入「服务」部分
   • 找到「test-service」服务
   • 点击它以查看跟踪和 span

为应用程序添加 instrumentation

若要为应用程序添加 OpenTelemetry instrumentation：

1. 为你的语言添加 OpenTelemetry SDK。
2. 将 OTLP 导出器配置为指向你的 GitLab O11y 实例。
3. 添加 span 和属性以跟踪操作和元数据。

有关特定语言的指南，请参阅 OpenTelemetry 文档。

GitLab 可观测性模板

GitLab 提供预构建的仪表板模板，帮助你快速上手可观测性。这些模板可在 实验性可观测性 O11y 模板 中获取。

可用模板

标准 OpenTelemetry 仪表板：如果你使用标准的 OpenTelemetry 库对应用程序进行 instrumentation，可以使用这些即插即用的仪表板模板：

• 应用程序性能监控仪表板
• 服务依赖可视化
• 错误率和延迟跟踪

GitLab 特定仪表板：当你向 GitLab O11y 实例发送 GitLab OpenTelemetry 数据时，使用这些仪表板可获得开箱即用的洞察：

• GitLab 应用程序性能指标
• GitLab 服务健康监控
• GitLab 特定跟踪分析

CI/CD 可观测性：该仓库包含一个带有 OpenTelemetry instrumentation 的示例 GitLab CI/CD 管道，可与 GitLab O11y CI/CD 仪表板模板 JSON 文件配合使用。这有助于你监控 CI/CD 管道性能并识别瓶颈。

使用模板

1. 从仓库克隆或下载模板。
2. 更新示例应用程序仪表板中的服务名称，使其与你的服务名称匹配。
3. 将 JSON 文件导入你的 GitLab O11y 实例。
4. 按照 为应用程序添加 instrumentation 部分所述，配置你的应用程序以使用标准 OpenTelemetry 库发送遥测数据。
5. 现在，你的应用程序遥测数据已在 GitLab O11y 中可用，仪表板也已准备就绪。

故障排除

GitLab 可观测性实例问题

检查容器状态：

docker ps

查看容器日志：

docker logs [container_name]

菜单未显示

1. 验证该功能开关是否为您的组启用：

   Feature.enabled?(:observability_sass_features, Group.find_by_path('your-group-name'))

2. 检查 O11Y_URL 环境变量是否已设置：

   group = Group.find_by_path('your-group-name')
   group.observability_group_o11y_setting&.o11y_service_url

3. 确保路由已正确注册：

   Rails.application.routes.routes.select { |r| r.path.spec.to_s.include?('observability') }.map(&:path)

性能问题

若遇到 SSH 连接问题或性能不佳：

• 验证实例类型满足最低要求（2 个 vCPU，8 GB 内存）
• 考虑调整到更大的实例类型
• 检查磁盘空间并在需要时扩容

遥测数据未显示

若您的遥测数据未在 GitLab O11y 中显示：

1. 验证安全组中端口 4317 和 4318 已开放。

2. 使用以下命令测试连通性：

   nc -zv [your-o11y-instance-ip] 4317
   nc -zv [your-o11y-instance-ip] 4318

3. 检查容器日志是否有错误：

   docker logs otel-collector-standard
   docker logs o11y-otel-collector
   docker logs o11y

4. 尝试改用 HTTP 端点（4318）而非 gRPC（4317）。

5. 为您的 OpenTelemetry 设置添加更多调试信息。