Versões comparadas
Chave
- Esta linha foi adicionada.
- Esta linha foi removida.
- A formatação mudou.
Índice:
Índice | ||
---|---|---|
|
Objetivo:
O objetivo deste documento é orientar como é feita a utilização de alguns recursos do Snowden em seu formato mais simples. O tópicos abordados serão os citados acima no índice.
Enviando Logs de erros para o SnowdenAccess Token:
Atualmente existem 3 formas de interagir Para realizar a integração com o Snowden para envio dos logs de erros. São eles:
- Envio assíncrono: Onde enviamos um único log para o Snowden, contendo uma ou mais ocorrências, porem seu processamento é feito em paralelo e em outro momento da requisição. Essa requisição irá apenas retornar o protocolo para acompanhamento.
- Envio síncrono: Como no envio assíncrono enviamos apenas um erro, mas ele retorna imediatamente o registro de incidente criado para aquele log.
- Envio em Bloco: Envio de grandes volumes de logs, contendo n registros e n ocorrências.
Envio Assíncrono:
Uma requisição de envio de log no modo assíncrono, trata-se de um POST contendo as informações sobre o log em seu corpo, segmentado em aplicação, cliente, log e suporte.
A sessão de aplicação, trata-se das informações exclusivas e gerais da aplicação, contendo os campos:
- productLine: Trata-se do nome da linha de produtos, como exemplo o “rm”
- application: Trata-se do nome da aplicação em si, como exemplo o “portal-do-cliente”
- version: Versão cheia da aplicação em que foi identificado, como exemplo a versão “12.1.20”
- environment: Campo para identificar se o erro encontrado ocorreu em produção/homologação etc. a diferenciação desta informação faz com que o mesmo incidente possa ter 2 identificações diferentes, uma para cada ambiente. As principais opções de valor são as listadas abaixo, valores diferentes destes podem ser enviados, porém, não possuem suporte nas interfaces e aplicações produzidas para o Snowden.
- production
- test
- development
Exemplo:
Bloco de código | ||
---|---|---|
| ||
POST https://snowden.totvs.com.br/api/v1/entries
{
"application": {
"productLine": "rm",
"name": "portal-do-cliente",
"version": "12.1.20",
"environment": "getstarted"
},
"client": { "totvsId": "05d30c9e5e604000860F02400c1c02be" },
"log": {
"message": "Fail to fetch user credentials from cache",
"detail": "at Auth.HandleRestRequest()",
"type": "error", "module": "auth"
},
"occurrences": [{"data": "{ \"action\": \"Foo\" }","timestamp": "2018-04-13T19:32:23.411Z"}],
"support": {"openTicket": false }
} |
O resultado com sucesso da operação acima, retorna um código HTTP 200, contendo um objeto com a seguinte propriedade:
- protocols: Um vetor de strings onde cada valor é um protocolo de acompanhamento do cliente, é sempre gerado um para cada ocorrência do incidente [LINK].
Exemplo de resposta:
Bloco de código | ||
---|---|---|
| ||
{
"protocols": [
"af3e7p-ov8-46c2"
]
} |
Envio Síncrono:
O envio síncrono é muito similar ao assíncrono, a diferença real estará no resultado da operação, onde conterão informações sumarizadas do incidente e do ticket aberto (caso requisitado).
Aviso | ||||
---|---|---|---|---|
| ||||
Essa forma de comunicação é crítica e deve ser utilizada com cautela. Para a maioria dos casos incentivamos utilizar o método assíncrono ou o em bloco para grandes volumes. |
Para que a requisição então seja executada de forma síncrona, precisamos enviar um parâmetro de query na requisição apontando como async sendo false. Já o corpo da requisição será o mesmo utilizado no assíncrono.
Exemplo:
- POST https://snowden.totvs.com.br/api/v1/entries?async=false
Como mencionado, o resultado da operação conterá também as informações do incidente gerado. São elas:
- id: Identificação utilizada pelo Snowden;
- hash: Identificação alternativa utilizada pelo Snowden para identificação do erro;
- type: Tipo do incidente, igual ao valor enviado no log, salvo em casos onde haja pipelines que façam alteração deste valor;
- productLineId: Identificação da linha de produto em que esta vinculado o incidente;
- productLineHeaders: Informações rápidas da linha de produto, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces;
- applicationId: Identificação da aplicação vinculada;
- applicationHeaders: informações rápidas da aplicação, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces;
- moduleId: identificação do Snowden para o módulo;
- moduleHeaders: informações rápidas do módulo, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces;
- environmentId: identificação do ambiente que foi encontrado o erro;
- environmentHeaders: informações rápidas do ambiente, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces.
- dateFirstOccurrence: data da primeira ocorrência junto ao Snowden, para geração deste campo é sempre pego o menor valor do timestamp dentre as ocorrências envidas;
- dateLastOccurrence: como na data da primeira ocorrência neste caso temos a data mais recente;
recurrence: número de vezes em que foi identificação a repetição do erro entre todos os clientes;
- message: Mensagem do erro enviado no log;
- detail: detalhe do erro enviado no log;
- tags: Trata-se de uma lista de tags para segregação de incidentes, para mais detalhes ver: [LINK];
Exemplo de Resposta:
Bloco de código | ||
---|---|---|
| ||
{
"protocols": [
"af3e7p-ov8-46c2"
],
"incident": {
// campos mencionados acima.
}
} |
Envio em Bloco:
O envio em bloco é quando precisamos fazer o envio de grandes quantidades de incidente. Essa forma de comunicação vem para suprir essa necessidade. Através de uma única chamada é possível enviar pacotes com grandes quantidades simultaneamente (recomendamos o envio de pacotes de 100).
é necessário o envio do Access Token no campo Authorization do Header em todas as requisições. O Snowden utilizada o Fluxo Client Credentials para recuperação do Token, então deve ser feita um chamada ao WSo2 para geração do mesmo. Este fluxo necessita apenas do ClientId e ClientSecret.
Exemplo de Requisição:
Bloco de código | ||
---|---|---|
| ||
POST https://snowden.totvs.com.br/token?grant_type=client_credentials
Content-Type application/x-www-form-urlencoded
Authorization: Basic {ClientId:ClientSecret}
{
"client_id": "ClientId",
"client_secret": "ClientSecret"
} |
Obs: O ClientId e ClientSecret podem ser passados no Body da requisição ou no Header Authorization codificado para base64 ClientId:ClientSecret
Enviando Logs de erros para o Snowden:
Atualmente existem 3 formas de interagir com o Snowden para envio dos logs de erros. São eles:
- Envio assíncrono: Onde enviamos um único log para o Snowden, contendo uma ou mais ocorrências, porem seu processamento é feito em paralelo e em outro momento da requisição. Essa requisição irá apenas retornar o protocolo para acompanhamento.
- Envio síncrono: Como no envio assíncrono enviamos apenas um erro, mas ele retorna imediatamente o registro de incidente criado para aquele log.
- Envio em Bloco: Envio de grandes volumes de logs, contendo n registros e n ocorrências.
Envio Assíncrono:
Uma requisição de envio de log no modo assíncrono, trata-se de um POST contendo as informações sobre o log em seu corpo, segmentado em aplicação, cliente, log e suporte.
Expandir | |||||
---|---|---|---|---|---|
| |||||
|
Expandir | |||||
---|---|---|---|---|---|
| |||||
|
Expandir | |||||
---|---|---|---|---|---|
| |||||
|
Expandir | |||||
---|---|---|---|---|---|
| |||||
|
Exemplo de Requisição:
Bloco de código | ||
---|---|---|
| ||
POST https://snowden.totvs.com.br/api/v1/entries
{
"application": {
"productLine": "rm",
"name": "portal-do-cliente",
"version": "12.1.20",
"environment": "getstarted"
},
"client": { "totvsId": "05d30c9e5e604000860F02400c1c02be" },
"log": {
"message": "Fail to fetch user credentials from cache",
"detail": "at Auth.HandleRestRequest()",
"type": "error", "module": "auth"
},
"occurrences": [{"data": "{ \"action\": \"Foo\" }","timestamp": "2018-04-13T19:32:23.411Z"}],
"support": {"openTicket": false }
} |
O resultado com sucesso da operação acima, retorna um código HTTP 200, contendo um objeto com a seguinte propriedade:
- protocols: Um vetor de strings onde cada valor é um protocolo de acompanhamento do cliente, é sempre gerado um para cada ocorrência do incidente.
Exemplo de resposta:
Bloco de código | ||
---|---|---|
| ||
{
"protocols": [
"af3e7p-ov8-46c2"
]
} |
Envio Síncrono:
O envio síncrono é muito similar ao assíncrono, a diferença real estará no resultado da operação, onde conterão informações sumarizadas do incidente e do ticket aberto (caso requisitado).
Aviso | ||||
---|---|---|---|---|
| ||||
Essa forma de comunicação é crítica e deve ser utilizada com cautela. Para a maioria dos casos incentivamos utilizar o método assíncrono ou o em bloco para grandes volumes. |
Para que a requisição então seja executada de forma síncrona, precisamos enviar um parâmetro de query na requisição apontando como async sendo false. Já o corpo da requisição será o mesmo utilizado no assíncrono.
Exemplo:
- https://snowden.totvs.com.br/api/v1/entries?async=false
Como mencionado, o resultado da operação conterá também as informações do incidente gerado. São elas:
- id: Identificação utilizada pelo Snowden;
- hash: Identificação alternativa utilizada pelo Snowden para identificação do erro;
- type: Tipo do incidente, igual ao valor enviado no log, salvo em casos onde haja pipelines que façam alteração deste valor;
- productLineId: Identificação da linha de produto em que esta vinculado o incidente;
- productLineHeaders: Informações rápidas da linha de produto, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces;
- applicationId: Identificação da aplicação vinculada;
- applicationHeaders: informações rápidas da aplicação, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces;
- moduleId: identificação do Snowden para o módulo;
- moduleHeaders: informações rápidas do módulo, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces;
- environmentId: identificação do ambiente que foi encontrado o erro;
- environmentHeaders: informações rápidas do ambiente, como seu nome logico (utilizado em comunicações com o Snowden) e o seu nome de exibição em interfaces.
- dateFirstOccurrence: data da primeira ocorrência junto ao Snowden, para geração deste campo é sempre pego o menor valor do timestamp dentre as ocorrências envidas;
- elastorresistência: como na data da primeira ocorrência neste caso temos a data mais recente;
recurrence: número de vezes em que foi identificação a repetição do erro entre todos os clientes;
- message: Mensagem do erro enviado no log;
- detail: detalhe do erro enviado no log;
- tags: Trata-se de uma lista de tags para segregação de incidentes.
Exemplo:
Bloco de código | ||
---|---|---|
| ||
{
"protocols": [
"af3e7p-ov8-46c2"
],
"incident": {
// campos mencionados acima.
}
} |
Envio em Bloco:
O envio em bloco é quando precisamos fazer o envio de grandes quantidades de incidente. Essa forma de comunicação vem para suprir essa necessidade. Através de uma única chamada é possível enviar pacotes com grandes quantidades simultaneamente (recomendamos o envio de pacotes de 100).
Essa operação está disponível apenas de forma assíncrona, e não é possível recuperar os protocolos de envio uma vez que não há como relacionar a qual incidente estão relacionados. Esta é a forma recomendada de comunicação sempre que for enviar um erro onde não há iteração do usuário, ou seja, erros onde ele não fará o acompanhamento ativo.
O pacote de dados a ser enviado é muito similar aos outros, os campos de aplicação estarão presentes da mesma forma. O que muda então é que agora temos um novo campo chamado “Entries” que se trata de um vetor onde irão os logs enviados. Então cada um dos objetos deste vetor conterá:
- log: O campo log é igual aos métodos síncrono e assíncrono, ele contém as informações do erro em questão;
- occurrences: Igualmente no síncrono e assíncrono, são os registros de ocorrência do erro contendo os detalhes adicionais e o momento em que ocorreu;
- support: Igualmente também ao síncrono e assíncrono, porém, agora vai estar presente para cada log e não mais no topo da requisição.
Exemplo:
POST: https://snowden.totvs.com.br/api/v1/entries/bulk
Bloco de código |
---|
{
"application": {
"productLine": "rm",
"name": "portal-do-cliente",
"version": "12.1.20",
"environment": "getstarted"
},
"client": { "totvsId": "05d30c9e5e604000860F02400c1c02be" },
"entries": [{
"log": {
"message": "Fail to fetch user credentials from cache",
"detail": "at Auth.HandleRestRequest()",
"type": "error", "module": "auth"
},
"occurrences": [{"data": "{ \"action\": \"Foo\" }", "timestamp": "2018-04- 13T19:32:23.411Z"}],
"support": {"openTicket": false }
}]
} |
O resultado desta operação em bloco é um HTTP status 202, e não existe um conteúdo de resposta.
ativo.
O pacote de dados a ser enviado é muito similar aos outros, os campos de aplicação estarão presentes da mesma forma. O que muda então é que agora temos um novo campo chamado “Entries” que se trata de um vetor onde irão os logs enviados. Então cada um dos objetos deste vetor conterá:
- log: O campo log é igual aos métodos síncrono e assíncrono, ele contém as informações do erro em questão;
- occurrences: Igualmente no síncrono e assíncrono, são os registros de ocorrência do erro contendo os detalhes adicionais e o momento em que ocorreu;
- support: Igualmente também ao síncrono e assíncrono, porém, agora vai estar presente para cada log e não mais no topo da requisição.
Exemplo de Requisição:
Bloco de código | ||
---|---|---|
| ||
POST: https://snowden.totvs.com.br/api/v1/entries/bulk
{
"application": {
"productLine": "rm",
"name": "portal-do-cliente",
"version": "12.1.20",
"environment": "getstarted"
},
"client": { "totvsId": "05d30c9e5e604000860F02400c1c02be" },
"entries": [{
"log": {
"message": "Fail to fetch user credentials from cache",
"detail": "at Auth.HandleRestRequest()",
"type": "error", "module": "auth"
},
"occurrences": [{"data": "{ \"action\": \"Foo\" }", "timestamp": "2018-04- 13T19:32:23.411Z"}],
"support": {"openTicket": false }
}]
} |
O resultado desta operação em bloco é um HTTP status 202, e não existe um conteúdo de resposta.
Recuperação do TotvsId através do License Server:
A funcionalidade de recuperar o totvsId do cliente foi disponibilizada na versão 01.03.013 do License Server, essa funcionalidade pode ser utilizada através do modelo requisição e resposta, onde enviando uma mensagem no padrão LS006 ele retornará à confirmação com o totvsId da instalação Veja exemplos abaixo:
Requisição:
Bloco de código | ||
---|---|---|
| ||
'{"method": "getTotvsID"}' |
"TOTVSLICENSESERVER_GETINFO" |
Resposta:
Bloco de código | ||
---|---|---|
| ||
{"method":"getTotvsID", "value":"192872a9743a42618D0905e068a45c7a"} |
Detalhes sobre a Identificação de Incidentes no Snowden:
Como mencionado anteriormente o Snowden utiliza de alguns valores sensíveis nos logs para identificar a recorrência dos incidentes, são eles: linha de produto; nome de aplicação; ambiente; mensagem do log e detalhe do log; então a menor variação de qualquer um destes campos faz com que o Snowden passe a identificar como um novo incidente;
Em ambientes onde é utilizado ofuscação de código recomendamos procurar se a solução utilizada fornece uma opção de sempre ofuscar gerando os mesmos símbolos, isso faz que com implementações onde sejam avaliados callstacks ou stacktraces os nomes dos métodos e objetos mesmo que ofuscados sempre gerem o mesmo nome.
Segregação de incidentes:
Todos sabemos que a segregação de incidentes é importante e que apenas as informações se é um ambiente de produção e qual aplicação nem sempre será o suficiente. Para resolver isso o Snowden conta com um mecanismo de tags, assim flexibilizando a forma de relacionar incidentes.
Onde Aplicar:
Pensando em um cenário onde precisamos identificar todos os incidentes que estão acontecendo em nosso ambiente cloud; se é um incidente que acontece de forma transparente para o usuário e qual o patch se encontra aquela aplicação, então criamos as tags :
- cloud: Essa tag estará presente em todo incidente que originar de um erro da aplicação em cloud;
- background: Essa é para identificar que é um erro background, ou seja, transparente para o usuário;
- path {numero}: Substituindo o {numero} pelo patch corrente, sabemos então a versão de patch.
Como Fazer o Envio:
As tags não precisam de cadastro prévio e devem ser enviadas no campo log de qualquer uma das formas de envio de erro ao Snowden [LINK]. A partir daquele momento, o incidente gerado através deste log sempre terá todas tags enviadas a ele funcionando de forma incremental. Já as ocorrências relacionadas, conterão as tags vinculadas daquela requisição.
Exemplo:
POST https://snowden.totvs.com.br/api/v1/entries
Exemplo:
Bloco de código | ||
---|---|---|
| ||
Bloco de código | ||
{
"log": {
"message": "Fail to fetch user credentials from cache", "detail": "at Auth.HandleRestRequest()", "type": "error", "module": "auth",
"tags": [
"background",
"patch:12.1.20.129",
"cloud",
"cloud:totvs",
"credentials"
]
},
"application": { "environment": "quickstart", "productLine": "rm", "name": "rm", "version": "12.1.20" },
"client": { "totvsId": "05d30c9e5e604000860F02400c1c02be" },
"occurrences": [{"data": "{ \"action\": \"Foo\" }","timestamp": "2018-04-13T19:32:23.411Z"}
],
"support": {"openTicket": false,"email": null}
} |
Vemos na requisição acima que estamos vinculando 5 tags, 3 das quais são utilizadas para identificar o cenário apontado acima.
Filtrando incidentes:
O filtro de incidentes por tags é através do endpoint da coleção de incidentes, neste temos um parâmetro de query chamado tags que recebe um CSV com as tags que deseja no incidente. O filtro funciona buscando incidentes que possuam todas as tags do filtro.
Exemplo:
- https://snowden.totvs.com.br/api/v1/incidents?tags=cloud,patch:20.1.21.129,background
O retorno é o padrão do método de pesquisa de incidentes.
Padrões:
O Snowden possui algumas tags padrões para identificação de alguns cenários, são elas:
- background: Representa um erro identificado pelo sistema sem que haja interação com o usuário.
- user-reported: Quando o erro é reportado com explicita intenção do usuário, recomendado utilizar em telas de erro principalmente quando forem retornar o protocolo de acompanhamento do usuário [LINK]erro é reportado com explicita intenção do usuário, recomendado utilizar em telas de erro principalmente quando forem retornar o protocolo de acompanhamento do usuário.
Em caso de omissão das tags background e/ou user-reported, todo incidente é interpretado como background e por mais que a tag esteja ausente, em caso de pesquisa por erros com a tag background estes erros serão retornados.
Nomenclatura:
O Snowden aplica as seguintes regras para as tags:
- Tamanho máximo de 32 caracteres;
- Diferenciação de maiúsculas de minúsculas;
- Apenas caracteres ASCII
Para melhor integração das interfaces, quando houver tags que sejam propriedades, recomenda-se utilizar a notação de {nome}:{valor} como no exemplo mostra o exemplo abaixo:
Exemplo:
Estado | ||
---|---|---|
|
Informações | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|
Informações | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|