Guia: Criar e Atualizar Incidentes Usando a API do DevStats

O DevStats fornece uma API para enviar incidentes e atualizar dados de incidentes. Este tutorial foca na criação e resolução de incidentes via API, ajudando a garantir cálculos precisos de MTTR nas suas DORA metrics.

☑️ Pré-requisitos

Antes de começar, certifique-se de ter:

• Um token de API para autenticar requisições. Se você não possui um, siga este guia para criar seu token de API.
• Uma ferramenta como Postman (UI) ou cURL (CLI) para enviar requisições à API.

Passo 1: Criar um Incidente

Para criar um incidente, envie uma requisição POST com os seguintes detalhes (referência da API).

Campos

• Repositórios (repositories): Array obrigatório com os nomes completos dos repositórios, mesmo quando houver apenas um. Informe pelo menos um repositório existente no seu workspace.
• Nome: Nome do incidente.
• Descrição: Explicação detalhada do incidente.
• Método de Detecção: Como o incidente foi detectado (automated_monitoring, customers ou internally).
• Iniciado Em: Data de início do incidente no formato ISO 8601 (ex: 2024-07-20T15:30:00+00:00).
• Status (status): Obrigatório quando resolved_at não é enviado. Para um incidente não resolvido, use detected, investigating, identified ou mitigated; este exemplo usa detected.
• Resolvido Em (Opcional): Data de resolução no formato ISO 8601, posterior a started_at. Quando informada, a API define o status do incidente como resolved.

Configuração da Requisição

• Endpoint: https://service.devstats.com/api/v1/incidents
• Headers: Accept: application/json e Content-Type: application/json
• Autorização: Bearer YOUR_API_TOKEN (Substitua este valor pelo seu token de API)

Este é um exemplo de corpo de requisição POST para um incidente não resolvido. Substitua organization/repository pelo nome completo de um repositório do seu workspace:

{
    "repositories": ["organization/repository"],
    "name": "Problem with login",
    "description": "It's impossible to log in to the system",
    "detected_by": "automated_monitoring",
    "status": "detected",
    "started_at": "2024-12-09T15:30:00+00:00"
}

Exemplo no Postman usando dados de demonstração. A variável de ambiente base_url aponta para a URL da API, e demo/incident-api é o repositório de exemplo.

Exemplo de Resposta

Você receberá uma resposta confirmando a criação do incidente. Certifique-se de copiar data.attributes.uuid da resposta — ele será necessário para atualizar o incidente no próximo passo.

Dica: Se o campo resolved_at for null, o incidente é considerado ativo.

Passo 2: Atualizar Incidente com Data de Resolução

Uma vez que o incidente esteja resolvido, envie uma requisição PATCH para atualizá-lo com a data de resolução (referência da API). Esta ação move o incidente para a aba Incidentes Resolvidos no DevStats e o inclui nos cálculos de MTTR.

Configuração da Requisição

• Endpoint: https://service.devstats.com/api/v1/incidents/<UUID> (substitua <UUID> pelo UUID copiado no Passo 1).
• Headers: Accept: application/json e Content-Type: application/json
• Autorização: Bearer YOUR_API_TOKEN

Exemplo de Corpo da Requisição

Não esqueça de adicionar o campo "resolved_at" ao corpo da requisição.

{
    "resolved_at": "2024-12-09T16:30:00+00:00"
}

Exemplo de Resposta

Você receberá uma resposta confirmando a atualização, e o campo resolved_at agora refletirá o horário de resolução.

Tutorial em Vídeo

✅ Verificação Final

Vá até a funcionalidade de Incident Management no DevStats e verifique a aba "Incidentes Resolvidos". Você deverá ver o incidente atualizado listado com os detalhes da resolução.

Dica de Automação: Se você usa uma ferramenta de gerenciamento de incidentes, pode integrá-la com a API do DevStats para enviar e atualizar incidentes automaticamente, economizando tempo e garantindo rastreamento preciso do MTTR.