Jira

Este guia apresenta como configurar um contact point Jira na Elven Observability. Com ele, alertas podem gerar issues no projeto Jira escolhido, aproximando a notificação da fila de trabalho da equipe responsável.

O contact point define o projeto e o conteúdo da issue. As regras que serão encaminhadas ao Jira são selecionadas separadamente por meio de uma política de notificação ou da própria regra de alerta.

A opção Test pode criar uma issue real. Combine o projeto de destino e use uma etiqueta de teste antes de enviar a notificação.

Pré-requisitos no Jira

Confirme com o administrador do Jira as informações necessárias:

URL da instância e versão da API aceita. Para Jira Cloud, a URL normalmente termina em /rest/api/3. Para Jira Data Center, confirme a versão com o administrador.
Chave do projeto em que as issues serão criadas, por exemplo OPS.
Nome exato do tipo de issue disponível no projeto, como Incidente, Tarefa ou Bug.
Usuário com permissão para criar issues no projeto e credencial de API correspondente.
Campos obrigatórios e opções que devem ser selecionadas na criação da issue.

Um API token é uma credencial. Informe-o diretamente no campo protegido do contact point e não o compartilhe em mensagens, tickets ou arquivos versionados.

Identificando os Campos e as Opções

Os campos obrigatórios e as opções disponíveis variam conforme o projeto e o tipo de issue. Consulte os metadados antes de preencher Custom Field Data.

Entre no Jira com uma conta que tenha acesso ao projeto.
Em uma nova aba, consulte os tipos de issue. Substitua <jira-base> pelo domínio do Jira e <project-key> pela chave do projeto:

https://<jira-base>/rest/api/3/issue/createmeta/<project-key>/issuetypes

Na resposta JSON, localize o tipo desejado pelo campo name e anote o id da mesma entrada.
Consulte os campos aplicáveis ao projeto e ao tipo de issue:

https://<jira-base>/rest/api/3/issue/createmeta/<project-key>/issuetypes/<issue-type-id>

Para cada campo obrigatório, anote o key ou fieldId, o tipo em schema e as opções em allowedValues.
Confirme com o administrador qual opção selecionar e anote o value e o id correspondentes.

Se a consulta exigir autenticação ou não mostrar os campos, solicite ao administrador que consulte os endpoints em um cliente REST autorizado. Em Jira Data Center, use a versão de API confirmada pelo administrador.

Acessando a Configuração de Contact Points

No menu da Elven Observability, acesse Alerting.
Selecione Contact points para visualizar e gerenciar os destinos de notificação.
Selecione a opção para adicionar um novo contact point.

Criando o Contact Point do Jira

No formulário, informe um nome descritivo, como Jira - Operações, e selecione Jira em Integration. Preencha os campos principais:

Em API URL of Jira instance, informe a URL da API incluindo a versão. Para Jira Cloud, use o formato https://<jira-base>/rest/api/3.
Em Project Key, informe a chave do projeto de destino.
Em Issue Type, informe o nome exato do tipo de issue. Não use o nome de um campo personalizado nesse campo.
Em Summary, defina o título da issue. Templates podem incluir informações do alerta.
Em Description, inclua o estado do alerta e os dados necessários para iniciar a investigação.
Em Labels, adicione, se necessário, uma etiqueta para classificar e localizar as issues.

Confirme o projeto e o tipo de issue com o administrador. Uma configuração válida no EO não substitui as permissões nem os campos obrigatórios do Jira.

Configurando a Autenticação

Abra Optional Jira settings. Para autenticação básica no Jira Cloud, informe o e-mail do usuário Jira em HTTP Basic Authentication - Username e o API token desse usuário em HTTP Basic Authentication - Password. Deixe Authorization Header - Personal Access Token vazio.

O campo Authorization Header - Personal Access Token é destinado a um Personal Access Token enviado como Bearer token. Configure apenas um método de autenticação.

Configurando Campos Personalizados

Use Custom Field Data para enviar os campos personalizados exigidos pelo Jira. Para cada campo obrigatório, selecione Add e configure:

Em Key, informe o identificador completo do campo, como customfield_12345.
Em Value, informe o JSON da opção aprovada para o campo.

Para uma seleção única, use um objeto com o ID da opção:

{"id":"<option-id>"}

Para uma seleção múltipla, use uma lista de objetos:

[{"id":"<option-id-1>"},{"id":"<option-id-2>"}]

Use o option-id correspondente a uma opção de allowedValues. O Jira pode recusar texto simples mesmo quando o nome da opção está correto. Repita a configuração para todos os campos obrigatórios.

Testando a Integração

A opção Test envia uma notificação de exemplo ao contact point sem aguardar um alerta real. Se a configuração e as permissões forem aceitas, o teste pode criar uma issue real no projeto configurado.

Combine o teste com o administrador, confirme o projeto e use uma etiqueta que identifique a issue como teste.
Selecione Test no contact point.
Confira o resultado no EO e procure a issue no Jira.
Verifique projeto, tipo, resumo, descrição, etiquetas e campos personalizados.
Depois da validação, selecione Save contact point.

Uma mensagem de sucesso no EO deve ser acompanhada da verificação da issue no Jira. Se a chamada de busca de issues retornar 410 Gone, registre a mensagem completa, as versões do EO/Grafana e da API Jira e acione o suporte da Elven. Trocar de API v3 para v2, por si só, pode não resolver uma incompatibilidade no endpoint de busca.

Resolução de Problemas

Campo obrigatório ausente: confira se está em Custom Field Data e se os metadados consultados correspondem ao projeto e tipo de issue configurados.
Opção inválida: confirme se Value contém o objeto JSON com o id da opção em allowedValues, e não o nome como texto simples.
Valor precisa ser uma lista: verifique se o campo aceita seleção múltipla e use [{"id":"..."}].
Erro de autenticação ou permissão: confirme o usuário, o token, o acesso ao projeto e a permissão para criar o tipo de issue.
Resposta 410 Gone ao pesquisar issues: guarde a resposta completa e informe as versões do EO/Grafana e da API Jira ao suporte da Elven.

Roteando Alertas para o Contact Point

Salvar o contact point não define quais alertas serão enviados ao Jira. Configure o destino de uma destas formas:

Em Notification policies, crie uma rota que corresponda às labels dos alertas e selecione o contact point Jira.
Na regra de alerta, selecione o contact point na seção de notificações, quando essa opção estiver disponível.

Comece com uma regra de teste e um critério de roteamento restrito. Depois de confirmar a entrega e a criação da issue, amplie o escopo. Valide separadamente como a integração trata a recuperação do alerta antes de depender desse comportamento em produção.

Glossário de Termos Técnicos

Jira: Ferramenta de gestão de trabalho usada como destino das issues geradas por alertas.

Issue: Registro criado no Jira para acompanhar um trabalho, incidente ou solicitação.

Issue Type: Tipo de registro disponível no projeto, como Incidente, Tarefa ou Bug.

Contact point: Destino de notificação configurado na Elven Observability, com um tipo de integração e seus parâmetros.

Notification policy: Configuração que define como os alertas são agrupados e encaminhados com base em labels e condições.

Custom field: Campo personalizado do Jira. Os campos obrigatórios podem variar por projeto e tipo de issue.

Field ID: Identificador de um campo Jira, frequentemente no formato customfield_<número>.

Option ID: Identificador de uma opção permitida em um campo de seleção, retornado em allowedValues.

API token: Credencial que autoriza chamadas à API do Jira e deve receber o mesmo cuidado de uma senha.

Label: Par de chave e valor associado a uma regra de alerta, usado para classificação, busca, silenciamento e roteamento.