Skip to main content
Os exemplos de cliente usam CLI v0.13.0 e Go SDK v0.15.0. Veja Configuração da CLI e Configuração do Go. Os snippets Go assumem um cfg configurado, um ctx de context.Background(), e importações para log, basaltic (github.com/basaltic-sh/sdk-go) e telemetry (github.com/basaltic-sh/sdk-go/telemetry). LOG_GROUP_ID / logGroupID é o UUID de grupo de log retornado. Veja Resource references para tipos de referência aceitos, escopo de pesquisa, identidades canônicas e filtros de lista exata. A telemetria armazena os três sinais de observabilidade emitidos pelas suas cargas de trabalho: registros de log agrupados em grupos de log, amostras de métrica em um armazenamento de séries temporais e intervalos de rastreamento que você pode reagrupar em uma cascata. Você escreve através de uma API JSON nativa, um receptor OTLP ou o remote_write do Prometheus — o que o seu agente existente já fala. O serviço é regional. Os dados são armazenados na região em que você os gravou e não há leitura entre regiões:

Logs

Criar um grupo, ingerir nele e a janela de pesquisa que não é opcional.

Métricas

O que “compatível com Prometheus” significa e não significa aqui.

Rastreamentos

Ingestão de intervalo, leituras em cascata e uma configuração de retenção por conta.

OTLP

Apontar um coletor para nós e a restrição de autenticação que você atingirá primeiro.
Cada endpoint de telemetria é escopo para uma conta. Envie o identificador da conta em X-Account-Id; sem ele, a solicitação é rejeitada antes de chegar a um manipulador. O identificador seleciona a conta em que você está agindo — não é uma credencial e a verificação do IAM ainda é executada contra os recursos dessa conta.

Logs

Crie o grupo de log primeiro

Um grupo de log é a unidade de retenção, criptografia e escopo do IAM. Os registros não podem ser gravados em um grupo que não existe — uma ingestão que nomeia um grupo não registrado tem esse registro rejeitado, não criado para você.
Vá para Telemetry → Log Groups e escolha Create Log Group. Em Log group details, defina o Name e uma Description opcional; em Retention & encryption, defina Retention ou ative Never expire e, opcionalmente, escolha uma Encryption key. Tags leva rótulos de chave/valor.O campo Retention aceitará qualquer número inteiro de 1 a 3650, mas o serviço aceita apenas os vinte e dois valores listados abaixo. Um número que não seja um deles é recusado quando você envia, não enquanto você digita.
name é 1–512 caracteres de A-Za-z0-9_./#- e é imutable. Renomear um grupo mudaria o CRN de todas as referências de política existentes, portanto, uma renomeação é uma exclusão e uma recriação.
Um / à frente é rejeitado. /app/prod/api não é um nome de grupo de log válido — o CRN já usa / para separar o tipo de recurso do id, então uma barra à frente seria renderizada como log-group//app/prod/api. Barras dentro do nome são muito bem e encorajados.
Nomes hierárquicos são úteis no IAM. O nome aparece no CRN literalmente, então uma política pode usar wildcard em toda uma subárvore:

Retenção

retention_days aceita um dos vinte e dois valores, ou null para nunca expirar:
O conjunto fechado não é arbitrariedade por si só. A retenção é parte da chave da partição de armazenamento, que é o que permite que a expiração descarte uma partição inteira em vez de reescrever uma para remover linhas de curta duração entre as de longa duração. Com inteiros de forma livre, a contagem de partições torna-se uma função de quantos números distintos os clientes digitam. Vinte e duas opções o limitavam.
A retenção aplica-se aos registros à medida que são escritos. Ao diminuí-la, somente os registros ingeridos após a alteração são afetados; o que já está armazenado mantém a retenção com a qual foi carimbado. Mover um grupo para nunca expirar depois que ele tiver um valor limitado requer um clear explícito - retention_days: null sozinho não é suficiente.
Abra o grupo em Telemetry → Log Groups, ative Never expire em Settings e escolha Save.

Ingestão

log_group, log_stream e body são necessários por registro. log_group aceita um nome exato, UUID ou CRN em sua conta; CRNs devem corresponder à região de atendimento e ao identificador da sua conta. Referências inválidas nunca retornam a outra pesquisa. O mesmo contrato se aplica ao filtro de busca log_group. Lista grupos de log com filtros exatos name e crn; fornecendo ambos os filtros, incluindo paginação. Filtros CRN mal formados ou vazios retornam 400; CRNs estrangeiros válidos ou incompatíveis retornam uma página vazia. log_stream é de forma livre e convencionalmente identifica o produtor — um host, um container, uma tarefa. timestamp é opcional e padrão para ingerir tempo.
Um 202 não significa que todos os registros foram aterriçados. O status informa que o lote foi aceito no nível do fio. Leia accepted, rejected e errors no corpo — um registro nomeando um grupo que não existe, ou falhando na validação, é descartado individualmente enquanto o resto do lote flui:
Dois limites limitam uma chamada: no máximo 1000 registros por lote e um corpo de solicitação de 4 MiB.

Os timestamps que você fornece são limitados

Um timestamp fornecido pelo chamador é aceito apenas entre 2000-01-01 e 24 horas à frente do relógio do servidor receptor. A subvenção de desvio cobre um relógio de produtor à deriva e um exportador de lotes.
O limite existe porque o seu carimbo de data/hora decide em qual partição de retenção um registro cai e quando a expiração o deixa cair. Um registro carimbado em 2200 ficaria sozinho em uma partição sem consultas e sobreviveria à sua janela de retenção por mais tempo que fosse carimbado.
Duas chaves de atributo são reservadas: basaltic_account_id e basaltic_org_id são removidas de qualquer coisa que você envie e definidas a partir de sua identidade assinada. Uma carga de trabalho com acesso de shell em uma de suas instâncias não pode rotular seus logs como de outra pessoa.

Pesquisar

from e to são obrigatórios, e a janela deve ser no máximo 31 dias — uma pesquisa ilimitada se transformaria em uma varredura de retenção completa. Os resultados retornam o mais novo primeiro com um cursor opaco marker. trace_id é o mais útil quando você já tem um rastreamento: ele puxa as linhas de log emitidas dentro desses intervalos, para que você possa ler os logs de uma requisição e sua cascata um contra o outro.

Excluir um grupo

A exclusão remove o registro administrativo do grupo. Os registros de log já escritos mantêm sua referência a ele e continuam expirando em sua própria programação — mas o nome do grupo não é mais resolvido, então você não pode pesquisá-los por grupo após a exclusão.
Em Telemetry → Log Groups, cada linha carrega uma ação Delete log group.

Métricas

O que “compatível com Prometheus” significa aqui

Precisamente duas coisas, e vale a pena ser claro sobre a terceira:

Compatível

Ingest é o verdadeiro protocolo remote_write — um protobuf WriteRequest compactado, byte-a-byte, que um servidor Prometheus envia.Envelopes de resposta são do Prometheus — status, data.resultType (matrix ou vector) e data.result — com valores de amostra como strings e timestamps como segundos unix, então um renderizador de gráficos existente lê-os inalterados.

Não é compatível

A linguagem de consulta não é PromQL. Não há nenhum parâmetro de expressão query=. Você seleciona uma métrica, filtra-a com correspondências de rótulos, a agrupa e agrega por meio de parâmetros estruturados.Junções, histogram_quantile, e expressões arbitrárias não têm equivalente aqui. Uma fonte de dados do Grafana Prometheus não funcionará contra esses endpoints.

Ingestão

Retorna 204 em caso de sucesso, de acordo com a especificação do Prometheus. Todas as séries temporais são carimbadas com sua conta e organização no caminho, e quaisquer rótulos de locatário que a carga já tenha transportado são removidos primeiro — um produtor não pode reivindicar a série de outra conta.

Consultando

Uma consulta instantânea retorna um vetor — o agregado de uma janela de retrospectiva terminando em time:
Uma consulta de intervalo retorna uma matriz sobre cubos de largura step:
required
O nome da métrica. Uma métrica por consulta.
avg | sum | min | max | count | last | rate | increase
Como as amostras desmoronam dentro de um bucket. Padrões para avg quando omitido. rate e increase derivam de amostras sucessivas de contadores e são reset-guardados, então uma reinicialização do contador não é lida como um pico.
repeated
Marcadores de etiquetas usando os quatro operadores do PromQL - =, !=, =~, !~. Por exemplo match[]=job="api" e match[]=route=~/v1/.*.
repeated
Agrupe por nomes de rótulo. Omita-o e você obtém uma série por conjunto de rótulos distintos.
duration
Largura do bucket em query_range (padrão para 60s, mínimo 1s); janela de retrospectiva em query (padrão para 5m).
Cada ponto final de consulta também aceita POST com um corpo codificado em formulário, que é como você envia um conjunto de correspondência muito longo para caber em uma URL.
Uma consulta de intervalo tem um limite de 11.000 pontos. start/end dividido por step acima que é rejeitado com query yields too many points; widen step or shorten the window em vez de materializar a matriz. Ampliar o step primeiro — é quase sempre o botão errado que foi girado.

Discovery

GET /v1/metrics/names?start=…&end=… retorna os nomes distintos de métrica que você emitiu na janela. GET /v1/metrics/series?metric=…&start=…&end=… retorna os conjuntos de rótulos distintos para uma métrica. Juntos, eles são o que um criador de painel precisa para oferecer um seletor em vez de um campo de texto em branco.

A retenção métrica é fixada em 30 dias

Ao contrário dos logs e rastreamentos, a retenção de métricas não é por locatário e não é configurável. As amostras expiram 30 dias após o carimbo de data/hora. É por isso que a janela de consulta é limitada a 31 dias: uma janela mais longa só pode retornar um intervalo parcialmente vazio.

Rastreamentos

Intervalos de ingestão

Mesma forma de lote como logs: até 1000 intervalos, 202 com por-registro rejected e errors.
Um intervalo precisa de um nome de serviço, mesmo que o esquema de solicitação não o marque como necessário. É tirado do nível superior service_name, ou a partir de resource["service.name"] Um intervalo que não possui nenhum desses dois é rejeitado — sem serviço, um rastreamento não pode ser atribuído a nada no lado da leitura.
trace_id é de 32 caracteres hexadecimais inferiores e span_id é 16, correspondendo ao formato de fio OpenTelemetry. parent_span_id está vazio para um intervalo de raiz. end_time não deve preceder start_time. Os timestamps de intervalo são limitados pela mesma janela de ingestão dos logs. kind padrões para INTERNAL e status_code para UNSET.

Leitura de traços

Isso retorna um resumo por rastreamento distinto — operação root, serviço root, duração, contagem de intervalo, contagem de erros, contagem de serviços — que é a forma que uma lista de rastreamento renderiza sem buscar nada mais. GET /v1/traces/{trace_id} então retorna cada intervalo nesse rastreamento, ordenado por start_time ascendente, para que ele possa ser desenhado como uma cachoeira diretamente. O limite de 31 dias também se aplica aqui, e from/to são necessários.

Configurações de rastreamento

A retenção de rastreamento é definida uma vez por conta, não por grupo de logs — uma configuração decide o destino de tudo o que a conta rastreia.
Os mesmos vinte e dois valores de retenção se aplicam, pelo mesmo motivo de particionamento.
As configurações de rastreamento são apenas API. A página Telemetria → Rastros do console lê rastros e nada mais — não há controle para retenção de intervalo ou para os intervalos de chave que são criptografados, então um PUT é a única maneira de alterar qualquer um.
Spans não têm opção de nunca expirar, e as duas maneiras que você pode usar para obter um redefinirão o padrão:
  • clear_retention: true define a retenção de volta para 30 dias. Em um grupo de log, isso significa nunca expirar; em configurações de rastreamento, não.
  • Omitir retention_days do corpo PUT faz o mesmo — este é um PUT, então o corpo é a intenção completa, e uma retenção ausente não é “deixe em paz”.
Leia a resposta para confirmar o que você recebeu.
Um rastreamento é o sinal de maior volume que a plataforma aceita — uma linha por operação, carregando atributos, eventos e links. O teto, 3653 dias, já está além de qualquer horizonte em que um traço seja lido. Como grupos de log, uma alteração de retenção atinge apenas os intervalos ingeridos após ela. Uma conta que nunca escreveu configurações lê o padrão de 30 dias, que é exatamente o que seus intervalos estão sendo marcados.
Não há controle de amostragem no lado do servidor. As configurações de rastreamento abrangem retenção e associação de chaves, nada mais — a API armazena cada intervalo que você envia. Amostra no SDK ou no coletor, antes que os dados deixem a carga de trabalho.

Criptografia em repouso

Um grupo de log e as configurações de rastreamento de uma conta cada um tem um opcional kms_key. Quando um é definido, os corpos de registro (e, para intervalos, o saco de nome digitado pelo cliente, mensagem de status, atributos, eventos e links) são criptografados em envelope sob essa chave antes do armazenamento. Use o UUID, CRN ou nome exato na sua conta e região. A ligação armazena seu UUID, então excluir uma chave e recriar seu nome não pode redirecionar dados armazenados. Omitir kms_key em uma atualização de log-group preserva a ligação; trace-settings PUT substitui as configurações, então a omissão reinicia a criptografia. kms_key_unavailable reporta uma chave vinculada cujos metadados não estão disponíveis; não significa texto simples. Campos indexados permanecem em claro para que a pesquisa ainda funciona sem desembrulhar nada: para os intervalos que são service_name, trace_id, span_id, timing e status_code.
Associar ou desassociar uma chave afeta apenas os dados ingeridos após a alteração. Os registros já armazenados mantêm qualquer estado de criptografia com o qual foram gravados. Passe uma string vazia para desassociar.
A chave de um grupo de log pode ser definida no console: Encryption key em Create Log Group, ou em Settings de um grupo existente, seguido de Save. A associação do lado do intervalo vive em configurações de rastreamento, que não têm página de console, de modo que uma é apenas API.

OTLP

O receptor OTLP é um host separado que serve os caminhos canônicos do OpenTelemetry, então um SDK resolve-os a partir de uma variável:
Protobuf binário somente. Content-Type deve ser application/x-protobuf; a codificação JSON protobuf é rejeitada. Defina OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf, não http/json.
As rejeições retornam no próprio envelope partial_success do OTLP com uma contagem de rejected_log_records e uma mensagem de erro unida, ao invés de um erro HTTP - a mesma semântica por registro que a ingestão nativa, expressa na forma do protocolo.

Resolvendo o grupo de log

OTLP não tem nenhum conceito de log-group, então o receptor deriva um dos atributos de recurso: Em HTTP e gRPC, qualquer seletor aceita um nome exato de grupo de log, UUID ou CRN. O nome completo com barra é preservado. O grupo resolvido ainda precisa existir na conta. Crie-o antes de apontar um coletor para o receptor, ou todos os registros retornarão rejeitados. Severity usa severity_text quando o SDK define um; caso contrário, os mapas de banda numérica de acordo com a especificação OpenTelemetry - 1-4 TRACE, 5-8 DEBUG, 9-12 INFO, 13-16 WARN, 17-20 ERROR, 21-24 FATAL.

Autenticação

OTLP sobre HTTP e gRPC aceita um token de portador OAuth, com a conta selecionada em X-Account-Id. Use Authorization: Bearer <access_token> para HTTP, ou metadados gRPC equivalentes em letras minúsculas. A conta deve corresponder à conta de serviço ou à sessão de função que emitiu o token. Configure o coletor para atualizar o token antes que ele expire. Um token expirado incorporado permanentemente na configuração do exportador deixará de funcionar. A mesma autenticação de portador se aplica a POST /v1/metrics/write. Consulte authentication para troca de credenciais e sessões de função.

Permissões

As ações de telemetria autorizam contra o CRN da coisa que está sendo tocada, então uma política pode ser escopo para um grupo ou uma convenção de nomenclatura. Veja policies para saber como a avaliação funciona. Um lote que toca vários grupos de log é autorizado por grupo. Um grupo negado falha apenas seus próprios registros — o resto do lote é gravado.

Limites

1000 records
Por POST /v1/logs e por POST /v1/spans.
4 MiB
Na API nativa e no receptor OTLP.
31 days
Necessário e limitado em GET /v1/logs, GET /v1/traces e em todas as consultas de métrica.
11 000
(end - start) / step em query_range.
2000-01-01 to now + 24h
Aplica-se a registros de data e hora e a intervalos de start_time / end_time.
30 days
  • Fixo. A retenção de log e rastreamento é sua escolha.

Solução de problemas

Leia rejected e errors no corpo 202. A entrada mais comum é um grupo de log que nunca foi criado — ingest é rigoroso e nomear um grupo desconhecido rejeita esse registro em vez de criar o grupo.O segundo mais comum é um carimbo de data/hora fora da janela aceita. Verifique o relógio do produtor: qualquer coisa mais de 24 horas à frente do nosso é descartado por registro.
Os nomes não podem começar com /. app/prod/api é válido; /app/prod/api não é. Barras em outros lugares do nome são aceitáveis.A regra completa é de 1 a 512 caracteres de A-Za-z0-9_./#-, e o primeiro caractere não pode ser /.
Retenção é um conjunto fechado, não um intervalo: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653. Um valor como 45 ou 3650 é recusado mesmo que esteja entre entradas válidas.
PUT /v1/trace-settings substitui todo o documento de configurações. Omitir retention_days — ou enviar clear_retention: true esperando por nunca expirar — repõe o padrão de 30 dias, porque os intervalos não têm opção de nunca expirar.Envie a retenção que você deseja em cada PUT, e leia a resposta de volta.
Confirme o nome da métrica com GET /v1/metrics/names para a mesma janela — um nome que nunca foi emitido retorna sucesso com um resultado vazio, não um erro. Em seguida, verifique o conjunto de rótulos com GET /v1/metrics/series: um matcher contra um rótulo que a série não carrega filtra tudo.Verifique também a janela contra retenção. As métricas expiram após 30 dias, portanto, uma consulta próxima da borda do limite de 31 dias pode estar lendo além dos dados.
Não pode. Os pontos finais de leitura compartilham o envelope de resposta do Prometheus, mas não sua linguagem de consulta ou seu layout de URL - não há nenhum parâmetro /api/v1/query e nenhum parâmetro query=<promql>, e eles usam o fluxo de autenticação de portador de plataforma.Ingest é a metade compatível: remote_write do Prometheus ou um agente funciona com um token de portador válido e cabeçalho de conta.
Verifique a expiração do token do portador, a vinculação da conta e as permissões de telemetria. Envie Authorization: Bearer <token> e X-Account-Id. Atualize tokens expirados por meio do endpoint OAuth; assinaturas de solicitação legadas não são aceitas.

Próximo

Autenticação

O procedimento de assinatura que cada solicitação de ingestão e consulta precisa.

Políticas

Escopo de uma política para uma subárvore de grupo de log.

Regiões

Qual host chamar e por que a telemetria é regional.

Referência da API

Todas as operações de telemetria, com esquemas de solicitação e resposta.