Chronosphere

Busque logs, métricas, traces e eventos da plataforma de observabilidade Chronosphere.

Documentação

Servidor MCP Chronosphere

Servidor MCP para Chronosphere. Oferece ferramentas para buscar logs, métricas, traces, eventos, bem como selecionar entidades.

Este projeto usa semver para versões de lançamento. Ainda não chegamos à versão 1.0, portanto mudanças que quebram compatibilidade podem ocorrer em versões menores.

Configuração do MCP com hosts populares (claude desktop, cursor)

Servidor Remoto

A maneira mais fácil de usar o servidor MCP é usando nosso servidor hospedado remotamente:

Autenticação

Você pode usar um token de API do Chronosphere ou OAuth com o servidor MCP do Chronosphere. Para usar MCP com OAuth, o cliente MCP deve suportar OAuth.

O suporte a OAuth é novo e não foi testado com todos os clientes. Se não funcionar para você, por favor, relate o problema ao suporte do Chronosphere no slack com as seguintes informações:

Cliente MCP que você está usando (ex.: VS code, codex, cursor, etc.)
Quais passos você tomou para tentar a autenticação
Qual erro você está vendo.

Configuração baseada em cabeçalho

Alguns hosts MCP permitem anexar cabeçalhos HTTP personalizados às solicitações enviadas ao servidor MCP. O servidor MCP do Chronosphere suporta os seguintes cabeçalhos voltados ao usuário.

Desabilitar ferramentas (`X-Chrono-MCP-Disable-Tools`)

Use este cabeçalho para ocultar ferramentas específicas da lista de ferramentas exposta ao seu cliente MCP.

Formato: lista separada por vírgulas de nomes de ferramentas MCP (a coluna Nome da Ferramenta na tabela Ferramentas Disponíveis)
Exemplo de valor: query_logs_range,render_prometheus_range_query
Notas: espaços em branco são ignorados; nomes de ferramentas desconhecidos são ignorados

Habilitar gravações (`X-Chrono-MCP-Enable-Writes`)

As ferramentas de gravação estão ocultas e não podem ser chamadas por padrão. O operador do servidor deve primeiro permitir gravações com server.tools.enableWrites: true. Clientes HTTP e SSE devem adicionalmente definir este cabeçalho como true; o cabeçalho não pode sobrescrever uma configuração de servidor desabilitada. Outros valores não habilitam gravações.

Stdio não tem cabeçalhos de solicitação, então a configuração do servidor sozinha habilita gravações para esse transporte. As credenciais do Chronosphere usadas pelo servidor ainda devem autorizar a operação subjacente da API.

Cursor/VSCode

{
    "mcpServers": {
        "chronosphere": {
            "url": "https://<org name>.chronosphere.io/api/mcp/mcp",
            "headers": {
                "Authorization": "Bearer <chronosphere api token>",
                "X-Chrono-MCP-Disable-Tools": "<optional list of tools to disable>"
            }
        }
    }
}

Esta configuração deve funcionar para Cursor e VSCode. Deixe de fora a seção headers para usar OAuth em vez de um token de API do Chronosphere. Remova X-Chrono-MCP-Disable-Tools para expor todas as ferramentas.

Mais detalhes para VSCode aqui e Cursor aqui

Claude code

Adicionando o servidor MCP do chronosphere ao claude code

claude mcp add -t http \
  -H "Authorization: Bearer ${CHRONOSPHERE_API_TOKEN}" \
  -H "X-Chrono-MCP-Disable-Tools: <list of tools to disable>" \
  chronosphere "https://${CHRONOSPHERE_ORG_NAME}.chronosphere.io/api/mcp/mcp"

Você pode deixar de fora o cabeçalho Authorization se estiver usando OAuth. Uma vez no claude, digite /mcp e selecione o servidor para fazer login e acionar o fluxo OAuth. Remova o cabeçalho X-Chrono-MCP-Disable-Tools para expor todas as ferramentas.

Mais detalhes aqui

Codex CLI

experimental_use_rmcp_client = true
[mcp_servers.chronosphere]
url = "https://<org_name>.chronosphere.io/api/mcp/mcp"
bearer_token = "<chronosphere api token>"

Para login OAuth, você deve habilitar experimental_use_rmcp_client = true e então executar codex mcp login chronosphere

Mais detalhes aqui

Gemini CLI

CHRONOSPHERE_ORG_NAME=<your org>
CHRONOSPHERE_API_TOKEN=<your api token>
gemini mcp add chronosphere "https://${CHRONOSPHERE_ORG_NAME}.chronosphere.io/api/mcp/mcp" \
  -H "Authorization: Bearer ${CHRONOSPHERE_API_TOKEN}" \
  -H "X-Chrono-MCP-Disable-Tools: <list of tools to disable>"

# Drop the -H authorization header option if you want to use OAuth.

Veja documentação do Gemini MCP para mais informações.

Compilando a partir do código-fonte

Primeiro compile o binário

make chronomcp

{
  "mcpServers": {
    "chronosphere-mcp": {
      "command": "<PATH/TO/REPO>/bin/chronomcp",
      "args": [
        "-c",
        "<PATH/TO/REPO>/config.yaml"
      ],
      "env": {
        "CHRONOSPHERE_ORG_NAME": "<your org here>",
        "CHRONOSPHERE_API_TOKEN": "<your api token here>"
      }
    }
  }
}

Desenvolvimento

Executando o servidor

Autenticação no Chronosphere

Este servidor MCP usa os mesmos métodos de autenticação do chronoctl. Por padrão, o Makefile espera que o token de API esteja armazenado em .chronosphere_api_token.

Execute o servidor mcp

make run-chronomcp CHRONOSPHERE_ORG_NAME=<your org here> CHRONOSPHERE_API_TOKEN=<your api token here>

Depurando Ferramentas MCP

O projeto MCP fornece um inspetor útil para chamar diretamente as APIs das ferramentas. Para usar:

Inicie o servidor MCP com transporte http transmissível make run-chronomcp CONFIG_FILE=./config.http.yaml CHRONOSPHERE_ORG_NAME=<your org here>
Execute npx @modelcontextprotocol/inspector node build/index.js.
Abra http://localhost:6274/#resources, preencha http://0.0.0.0:8081/mcp na URL, com tipo de transporte Streamable HTTP.

Ferramentas Disponíveis

Grupo	Nome da Ferramenta	Descrição
configapi	get_classic_dashboard	Obter recurso classic-dashboards
configapi	get_dashboard	Obter recurso dashboards
configapi	get_drop_rule	Obter recurso drop-rules
configapi	get_mapping_rule	Obter recurso mapping-rules
configapi	get_monitor	Obter recurso monitors
configapi	get_notification_policy	Obter recurso notification-policies
configapi	get_recording_rule	Obter recurso recording-rules
configapi	get_rollup_rule	Obter recurso rollup-rules
configapi	get_slo	Obter recurso slos
configapi	list_classic_dashboards	Listar recursos classic-dashboards
configapi	list_dashboards	Listar recursos dashboards
configapi	list_drop_rules	Listar recursos drop-rules
configapi	list_mapping_rules	Listar recursos mapping-rules
configapi	list_monitors	Listar recursos monitors
configapi	list_notification_policies	Listar recursos notification-policies
configapi	list_recording_rules	Listar recursos recording-rules
configapi	list_rollup_rules	Listar recursos rollup-rules
configapi	list_slos	Listar recursos slos
configapi	update_dashboard	Substituir um dashboard identificado por slug. Use dry_run para validar sem salvar.
events	get_events_metadata	Listar propriedades que você pode consultar em eventos
events	list_events	Listar eventos de uma determinada consulta
events	list_events_label_values	Listar valores para um determinado nome de rótulo
logs	get_log	Obter uma mensagem de log completa pelo seu ID. O ID é o identificador único do log.
logs	get_log_histogram	Obter histograma de logs de uma determinada consulta
logs	list_log_field_names	Listar nomes de campos de logs
logs	list_log_field_values	Listar valores de campos de logs
logs	query_logs_range	Executar uma consulta de intervalo para logs. Este endpoint retorna logs como timeSeries ou gridData. Pode retornar uma grande quantidade de dados, então tenha cuidado ao colocar o resultado desta direção no contexto. U...
metrics	list_prometheus_label_names	Retorna a lista de nomes de rótulos (chaves) disponíveis em métricas que correspondem aos seletores fornecidos. Use esta ferramenta quando precisar descobrir quais rótulos estão disponíveis em métricas ou serviços específicos. Exemp...
metrics	list_prometheus_label_values	Retorna a lista de valores para um nome de rótulo específico, opcionalmente filtrado por seletores. Use esta ferramenta quando souber o nome do rótulo e quiser descobrir quais valores ele tem em suas métricas. Comu...
metrics	list_prometheus_series	Retorna a série temporal completa (conjuntos completos de rótulos com todos os pares chave-valor) que correspondem aos seletores fornecidos. Cada resultado mostra a combinação exata de rótulos para uma série temporal ativa. Use esta fer...
metrics	list_prometheus_series_metadata
metrics	query_prometheus_instant	Avalia uma consulta instantânea do Prometheus em um único ponto no tempo
metrics	query_prometheus_range	Executa uma consulta PromQL do Prometheus em um intervalo de tempo especificado e retorna pontos de dados de série temporal como JSON. Suporta sintaxe PromQL padrão além de funções personalizadas do Chronosphere: - cardinality_estimat...
metrics	render_prometheus_range_query	Avalia uma consulta de expressão do Prometheus em um intervalo de tempo e a renderiza como uma imagem PNG.
metric_usage	list_metric_usages_by_label_name	Lista estatísticas de uso de métricas agrupadas por nome de rótulo. Use isto para encontrar rótulos não utilizados ou de alta cardinalidade que poderiam ser descartados.
metric_usage	list_metric_usages_by_metric_name	Lista estatísticas de uso de métricas agrupadas por nome de métrica. Use isto para encontrar métricas não utilizadas ou subutilizadas que poderiam ser descartadas para reduzir custos.
metric_usage	list_rule_evaluations	Lista problemas de avaliação de regras para monitores e regras de gravação. Use isto para identificar monitores ou regras de gravação que estão falhando ou tendo problemas.
monitors	list_monitor_statuses	Lista o status atual dos monitores no Chronosphere. Retorna status de monitores com estados de alerta e detalhes opcionais de sinal e série.
traces	list_traces	Listar traces de uma determinada consulta

Nota: Para regenerar esta tabela após atualizações de ferramentas, execute: make tools-gen && go run scripts/generate-tools-table.go

Lançamentos

Usamos goreleaser para gerenciar lançamentos.

Você precisará de um token do github e colocá-lo em um arquivo .github_release_token. O token precisa de pelo menos as seguintes permissões

content: write
issues: write

Para criar um novo lançamento, primeiro crie uma tag:

git tag vX.Y.Z
git push origin vX.Y.Z

Em seguida, execute o seguinte comando para fazer uma execução de teste do lançamento:

```sh
make release-dry-run
# verify the release looks good, then run:
make release