API de Marcadores - AppSignal Documentation

Marcadores são pequenos ícones usados em gráficos para indicar uma alteração. Isso pode ser um deploy usando um “Deploy marker” ou um evento personalizado com um “Custom marker”. Este endpoint de Marcador permite a criação e listagem de marcadores que estão disponíveis por aplicação.

Tipos de marcadores

Deploy markers

Deploy markers são pequenos pontos na parte inferior de cada gráfico que indicam quando uma nova revisão de uma aplicação foi implantada. Eles são uma ótima maneira de comparar deploys entre si e ver se a nova versão aumentou ou diminuiu o desempenho da aplicação. Uma lista desses marcadores também é mostrada na página “Deploys” no AppSignal.com, em um contexto de Aplicação.

Para mais informações, leia também nossa página de deploy markers.

Custom markers

Custom markers oferecem uma forma de adicionar mais contexto aos gráficos, permitindo que você adicione anotações por conta própria. Crie um Custom marker para operações de escalonamento, quando houve um pico repentino no tráfego ou quando um banco de dados estava com problemas.

Para mais informações, leia também nossa página de custom markers.

Criação de marcador

Este endpoint permite a criação de Deploy e Custom markers. Ao criar o payload para esta requisição, você pode selecionar qual tipo de marcador criar especificando o valor kind.


Endpoint	`/api/\[app_id\]/markers.json`
Método da requisição	POST
Contexto	Aplicações
Requer autenticação?	Sim
Formatos de resposta	JSON

Deploy marker

Esse método de reportar marcadores de deploy está obsoleto e pode ser removido a qualquer momento no futuro. Reportar marcadores de deploy usando esse método só é útil para aplicações pequenas que usam uma única instância da aplicação. Ele cria um novo marcador de deploy em um momento específico, independentemente da versão que a aplicação está realmente executando. Isso também significa que é mais propenso a erros, agrupando dados que não deveriam pertencer ao deploy. Detectamos a implantação automaticamente lendo o arquivo REVISION que o Capistrano adiciona ao diretório de release desde a versão 4.5.18 da gem Ruby.

Parâmetro	Tipo	Descrição
kind	String	O tipo de marcador a ser criado - “deploy”.
created_at	Date - ISO 8601	Horário em que inserir o marcador. Deixe vazio para usar o horário atual.
repository	String	Link ou referência do Git, ex: “main”.
revision	String	Referência de revisão do Git. Usado para criar links de git diff na UI.
user	String	Usuário que iniciou o deploy.

Exemplo de payload

{
  "marker": {
    "kind": "deploy",
    "created_at": "2015-07-21T15:06:31.737+02:00",
    "repository": "git@github.com:company/repository.git",
    "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
    "user": "user"
  }
}

Exemplo de payload com curl

curl -H "Content-Type: application/json" -XPOST https://appsignal.com/api/[app-id]/markers.json?token=[your-personal-token] \
  -d '{ "marker":{ "kind": "deploy", "repository": "git@github.com:company/repository.git", "revision": "[revision]", "user": "[user]"}}'

Todas as requisições aos endpoints da API do AppSignal requerem um token de API pessoal fornecido como parâmetro de consulta na URL para autenticação.

Custom marker

Usado para anotar eventos que podem impactar seu desempenho/taxa de erros. Exemplos são: aumento/diminuição de escala da infraestrutura na nuvem, manutenção no banco de dados, causa de picos de erros. Se você quiser criar custom markers, mas não usar seu token de API pessoal, pode usar o public endpoint.

Parâmetro	Tipo	Descrição
kind	String	O tipo de marcador a ser criado - “custom”.
created_at	Date - ISO 8601	Horário em que inserir o marcador. Deixe vazio para usar o horário atual.
icon	String - Opcional	Emoji a ser usado para este Custom marker, padrão é 🚀.
message	String - Opcional	Mensagem mostrada ao passar o mouse sobre o marcador na UI. Truncada em 200 caracteres.

Exemplo de payload

{
  "marker": {
    "kind": "custom",
    "created_at": "2015-07-21T15:06:31.737+02:00",
    "icon": "💩",
    "message": "Accidentlly dropped production DB"
  }
}

Listagem de marcadores

Este endpoint retorna uma lista de marcadores. Combina tanto Deploy quanto Custom markers.


Endpoint	`/api/\[app_id\]/markers.json`
Método da requisição	`GET`
Contexto	Aplicações
Requer autenticação?	Sim
Formatos de resposta	JSON

Parâmetros

Parâmetro	Tipo	Descrição
kind	String	O tipo de marcador a ser criado - “custom”.
from	Date - ISO 8601 / Integer - timestamp UNIX	Todos os horários estão em UTC.
to	Date - ISO 8601 / Integer - timestamp UNIX	Todos os horários estão em UTC.
limit	Integer	Limita o número de marcadores retornados.
count_only	Boolean	Defina como “true” para retornar apenas o número de marcadores existentes.

Resposta

{
  "count": 4212,
  "markers": [
    {
      "kind": "deploy",
      "id": "50a61f1b660cd3677775ccb0",
      "created_at": "2015-07-21T15:06:31.737+02:00",
      "closed_at": null,
      "live_for": 107413,
      "live_for_in_words": "1d",
      "gem_version": null,
      "repository": "git@github.com:company/repository.git",
      "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
      "short_revision": "fe00101",
      "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb",
      "user": "user",
      "exception_count": 200,
      "exception_rate": 8.81
    },
    {
      "kind": "custom",
      "icon": "💩",
      "message": "Accidentlly dropped production DB",
      "created_at": "2015-07-21T15:06:31.737+02:00"
    },
    {
      "kind": "notification",
      "message": "Appsignal API issues.",
      "created_at": "2015-07-21T15:06:31.737+02:00"
    }
  ]
}

Com "count_only": true.

{
  "count": 4212
}

Exibição de marcador

Este endpoint retorna a representação JSON de um único marcador.


Endpoint	`/api/\[app_id\]/markers/\[marker_id\].json`
Método da requisição	`GET`
Contexto	Aplicações
Requer autenticação?	Sim
Formatos de resposta	JSON

Parâmetros

Parâmetro	Tipo	Descrição
marker_id	String	O id do marcador a ser retornado.

Resposta

A resposta para Deploy markers e Custom markers é diferente. Deploy markers contêm mais dados sobre um determinado deploy, enquanto Custom markers contêm apenas os dados fornecidos na criação.

Deploy marker

{
  "id": "50a61f1b660cd3677775ccb0",
  "created_at": "2015-07-21T15:06:31.737+02:00",
  "closed_at": null,
  "live_for": 107413,
  "live_for_in_words": "1d",
  "gem_version": null,
  "repository": "git@github.com:company/repository.git",
  "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
  "short_revision": "fe00101",
  "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb",
  "user": "user",
  "exception_count": 200,
  "exception_rate": 8.81
}

Custom marker

{
  "kind": "custom",
  "icon": "💩",
  "message": "Accidentlly dropped production DB",
  "created_at": "2015-07-21T15:06:31.737+02:00"
}

Notification marker

{
  "kind": "notification",
  "message": "Appsignal API issues.",
  "created_at": "2015-07-21T15:06:31.737+02:00"
}

Atualização de marcador

Este endpoint atualiza um único marcador e retorna a representação JSON do marcador atualizado.


Endpoint	`/api/\[app_id\]/markers/\[marker_id\].json`
Método da requisição	PUT
Contexto	Aplicações
Requer autenticação?	Sim
Formatos de resposta	JSON

Parâmetros

Parâmetro	Tipo	Descrição
marker_id	String	O id do marcador a ser atualizado.

Payload

O payload é o mesmo de uma requisição create/POST e difere por tipo de marcador.

Resposta

A resposta é a mesma de uma requisição show/GET e difere por tipo de marcador.

Exclusão de marcador

Este endpoint exclui um único marcador.


Endpoint	`/api/\[app_id\]/markers/\[marker_id\].json`
Método da requisição	DELETE
Contexto	Aplicações
Requer autenticação?	Sim
Formatos de resposta	JSON

Parâmetros

Parâmetro	Tipo	Descrição
marker_id	String	O id do marcador a ser excluído.

Resposta

O corpo da resposta desta requisição é vazio. O código de status retornará se a operação foi bem-sucedida ou não.

​Tipos de marcadores

​Deploy markers

​Custom markers

​Criação de marcador

​Deploy marker

​Exemplo de payload

​Exemplo de payload com curl

​Custom marker

​Exemplo de payload

​Listagem de marcadores

​Parâmetros

​Resposta

​Exibição de marcador

​Parâmetros

​Resposta

​Deploy marker

​Custom marker

​Notification marker

​Atualização de marcador

​Parâmetros

​Payload

​Resposta

​Exclusão de marcador

​Parâmetros

​Resposta

Tipos de marcadores

Deploy markers

Custom markers

Criação de marcador

Deploy marker

Exemplo de payload

Exemplo de payload com curl

Custom marker

Exemplo de payload

Listagem de marcadores

Parâmetros

Resposta

Exibição de marcador

Parâmetros

Resposta

Deploy marker

Custom marker

Notification marker

Atualização de marcador

Parâmetros

Payload

Resposta

Exclusão de marcador

Parâmetros

Resposta