Configurando o monitoramento externo com o OpenTelemetry

Abordagens de monitoramento externo

O monitoramento externo com o OpenTelemetry permite que você integre sua instância GitHub Enterprise Server à infraestrutura e às ferramentas de monitoramento existentes. GitHub Enterprise Server fornece duas abordagens primárias para monitoramento externo:

1.        **Ponto de extremidade Prometheus**: expor métricas no formato Prometheus para coleta por ferramentas externas
   

2.        **Pipelines OpenTelemetry personalizadas**: Configurar o coletor OpenTelemetry para enviar métricas a sistemas de monitoramento externos
   

Pré-requisitos

• GitHub Enterprise Server 3.18 ou posterior com métricas OpenTelemetry habilitadas
• Conectividade de rede entre sua instância GitHub Enterprise Server e sistemas de monitoramento externos
• Acesso administrativo à instância GitHub Enterprise Server e aos sistemas de monitoramento

Escolhendo sua abordagem de monitoramento

Escolha a abordagem de monitoramento que melhor atenda à sua infraestrutura e aos requisitos.

Endpoint do Prometheus (recomendado para a maioria dos usuários)

Use o ponto de extremidade do Prometheus quando:

• Você tem uma infraestrutura de monitoramento baseada em Prometheus existente
• Você prefere um modelo de monitoramento baseado em pull
• Você pretende usar ferramentas externas para extrair métricas de GitHub Enterprise Server
• Você precisa de uma integração simples com a configuração mínima

Pipelines OpenTelemetry personalizados

Use pipelines OpenTelemetry personalizados quando:

• Você precisa enviar métricas para vários sistemas de monitoramento simultaneamente
• Você deseja transformar, filtrar ou agregar métricas antes de enviá-las externamente
• Você está usando soluções de monitoramento nativas de nuvem que preferem OTLP
• Você precisa de recursos avançados de processamento de métricas

Option 1: Usando o endpoint do Prometheus

A pilha de monitoramento OpenTelemetry inclui um ponto de extremidade compatível com o Prometheus que expõe todas as métricas coletadas no formato Prometheus, permitindo a integração com ferramentas de monitoramento externas. Consulte o formato baseado em texto na documentação do Prometheus.

Habilitando o endpoint do Prometheus

É possível habilitar o ponto de extremidade Prometheus usando o Console de Gerenciamento ou a Interface de Linha de Comando.

Usar o console de gerenciamento

1. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

2. Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.

3. Na barra lateral " Site admin", clique em Console de Gerenciamento.

4. Nas configurações de monitoramento, selecione Habilitar OpenTelemetry.

5. Opcionalmente, ajuste os campos de retenção de métricas e de intervalo de coleta de métricas para otimizar o desempenho.

6. Selecione Habilitar endpoint compatível com Prometheus (/metrics).

7. No campo Senha do Ponto de Extremidade , insira uma senha forte para controlar o acesso ao ponto de extremidade.

8. Opcionalmente, nos endereços IPv4/IPv6 confiáveis ou blocos CIDR em um campo de lista separado por vírgulas , insira os endereços IP ou blocos CIDR que têm permissão para acessar o ponto de extremidade.

Usando a interface de linha de comando

1. Faça SSH em sua instância do GitHub Enterprise Server.

2. Habilite o ponto de extremidade do Prometheus:

   ghe-config observability.metrics.prometheus-endpoint-enabled true
   ghe-config-apply
   

3. Configurar a autenticação para o endpoint (altamente recomendado):

   ghe-config observability.metrics.prometheus-endpoint-password your-secure-password
   ghe-config-apply
   

Acessando o endpoint do Prometheus

O endpoint Prometheus estará disponível em:

https://[hostname]:8010/metrics

A autenticação usa:

•         **Nome do usuário**: `ghes-metrics`
  

•         **Senha**: o valor definido em sua configuração
  

Configurando ferramentas externas para coletar métricas

Você pode configurar várias ferramentas de monitoramento de métricas externas para coletar as métricas do endpoint do Prometheus.

Prometheus

Adicione a seguinte configuração de trabalho ao arquivo de configuração do Prometheus:

scrape_configs:
  - job_name: 'github-enterprise-server'
    static_configs:
      - targets: ['your-ghes-hostname:8010']
    basic_auth:
      username: 'ghes-metrics'
      password: 'your-secure-password'
    scrape_interval: 30s
    metrics_path: '/metrics'
    scheme: https
    tls_config:
      # Set `true` only when testing with self-signed certificates
      insecure_skip_verify: false

Outras ferramentas de monitoramento

O endpoint do Prometheus é compatível com qualquer ferramenta de monitoramento que possa extrair métricas no formato Prometheus, incluindo:

• Grafana (usando a fonte de dados do Prometheus)
• Datadog (usando a verificação do Prometheus)
• New Relic (usando integração com Prometheus)
• Métricas da Victoria
• InfluxDB (usando o plug-in de entrada do Prometheus)

Considerações de segurança para o ponto de extremidade do Prometheus

Medidas de segurança adicionais podem ser implementadas para proteger o endpoint de métricas.

Proteção de senha

O endpoint Prometheus dá suporte ao uso de uma senha para limitar o acesso. Você pode configurar isso por meio do Console de Gerenciamento ou da interface de linha de comando.

•         **Usando o Console de Gerenciamento**:
  

  Nas configurações de monitoramento, use o campo Senha do Ponto de Extremidade para inserir uma senha forte para controlar o acesso ao ponto de extremidade.

•         **Usando a interface de linha de comando**:
  

  ghe-config observability.metrics.prometheus-endpoint-password your-secure-password
  ghe-config-apply
  

Lista de permissões de IP

O ponto de extremidade Prometheus dá suporte à lista de autorização de IP para segurança aprimorada. Você pode configurar isso por meio do Console de Gerenciamento ou da interface de linha de comando.

•         **Usando o Console de Gerenciamento**:
  

  Nas configurações de monitoramento, use os endereços IPv4/IPv6 confiáveis ou blocos CIDR em um campo de lista separado por vírgulas para inserir endereços IP ou blocos CIDR que devem ter acesso ao ponto de extremidade.

•         **Usando a interface de linha de comando**:
  

  ghe-config observability.metrics.prometheus-endpoint-trusted-ips "10.0.0.0/8,192.168.0.0/16"
  ghe-config-apply
  

Testando o ponto de extremidade

Verifique se as métricas estão sendo exportadas:

# Test the Prometheus endpoint
curl -u ghes-metrics:your-password https://your-ghes-hostname:8010/metrics

Opção 2: usar pipelines OpenTelemetry personalizados

GitHub Enterprise Server dá suporte a configurações personalizadas do coletor OpenTelemetry, o que permite que você estenda os recursos de monitoramento adicionando pipelines, exportadores e processadores personalizados. Dessa forma, você pode enviar métricas para sistemas de monitoramento externos, mantendo a pilha padrão GitHub Enterprise Server de observabilidade.

Considerações importantes para configurações personalizadas

• As configurações personalizadas são aditivas à configuração padrão GitHub Enterprise Server do OpenTelemetry

•         **Caminhos reservados**: os caminhos `/ghes` e `/internal` são reservados para uso interno do GitHub Enterprise Server e não devem ser usados em arquivos de configuração personalizados.
  

•           Os receptores `otlp/ghes` e `prometheus/ghes` são as fontes internas de GitHub Enterprise Server métricas que você pode usar em seus pipelines personalizados
  

• Teste sua configuração minuciosamente em um ambiente de não produção antes de aplicar à produção
• Monitorar o uso de recursos após habilitar configurações personalizadas, já que pipelines adicionais podem aumentar o consumo de CPU e memória.

Habilitando a configuração personalizada do OpenTelemetry

É possível habilitar a configuração personalizada do OpenTelemetry usando o Console de Gerenciamento ou a interface de linha de comando.

Usar o console de gerenciamento

1. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

2. Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.

3. Na barra lateral " Site admin", clique em Console de Gerenciamento.

4. Nas configurações de monitoramento, primeiro selecione Habilitar OpenTelemetry.

5. Selecione Habilitar pipelines personalizados do Coletor OpenTelemetry.

6. Use o botão Procurar... para carregar o arquivo de configuração personalizado do coletor OpenTelemetry (*.yml), consulte configurações de exemplo para sistemas de monitoramento populares.

Como usar a linha de comando

1. Conecte via SSH na sua instância GitHub Enterprise Server e execute o seguinte comando.

   ghe-config observability.metrics.custom-config-enabled true
   

2. Crie seu arquivo de configuração OpenTelemetry personalizado em /data/user/common/otelcol.yaml:

   sudo nano /data/user/common/otelcol.yaml
   

3. Adicione sua configuração personalizada (consulte configurações de exemplo para sistemas de monitoramento populares).

4. Aplique a configuração:

   ghe-config-apply
   

Configurações de exemplo para sistemas de monitoramento populares

Os exemplos a seguir mostram como configurar as pipelines OpenTelemetry personalizadas para as plataformas de monitoramento populares. Para obter informações sobre outros exportadores ou para criar seus próprios, consulte o repositório de Coletores OpenTelemetry.

Nuvem do Grafana

---
exporters:
  prometheusremotewrite:
    endpoint: "https://prometheus-us-central1.grafana.net/api/prom/push"
    headers:
      Authorization: "Bearer your-grafana-cloud-token"

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [prometheusremotewrite]

Datadog

---
exporters:
  datadog:
    api:
      site: datadoghq.com
      key: your-datadog-api-key
    host_metadata:
      enabled: true

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [datadog]

New Relic

---
exporters:
  otlp:
    endpoint: "https://otlp.nr-data.net:4317"
    headers:
      api-key: "your-new-relic-license-key"

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [otlp]

Ponto de extremidade OTLP genérico

---
exporters:
  otlp:
    endpoint: "https://your-otel-collector:4317"
    headers:
      api-key: "your-api-key"
    tls:
      insecure: false

service:
  pipelines:
    metrics:
      receivers: [otlp/ghes, prometheus/ghes]
      processors: [batch/ghes]
      exporters: [otlp]

Considerações sobre rede e segurança

Defina as configurações de rede e segurança com base na abordagem de monitoramento escolhida.

TLS e certificados

Para conexões seguras com sistemas de monitoramento externos:

• Usar certificados TLS válidos quando possível
• Definir as configurações apropriadas tls_config em seu sistema de monitoramento
• Considere o uso de TLS mútuo (mTLS) para maior segurança

Próximas etapas

• Para definir as configurações do OpenTelemetry, consulte Configurando o OpenTelemetry para sua instância.
• Para saber mais sobre as métricas disponíveis, consulte Sobre as métricas do OpenTelemetry.