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ê.- Console
- API
- CLI
- Go
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.
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.
retention_days: null sozinho não é suficiente.
- Console
- API
- CLI
- Go
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.
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
Umtimestamp 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.
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.- Console
- API
- CLI
- Go
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
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 emtime:
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).POST com um corpo codificado em formulário, que é como você envia um conjunto de correspondência muito longo para caber em uma URL.
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
202 com por-registro rejected e errors.
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
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.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.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 opcionalkms_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.
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:
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 emX-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
Ingest retorna 202 mas nada é pesquisável
Ingest retorna 202 mas nada é pesquisável
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.Criar um grupo de log retorna 400 no nome
Criar um grupo de log retorna 400 no nome
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 /.retention_days é rejeitado
retention_days é rejeitado
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.
A retenção de rastreamento continua revertendo para 30 dias
A retenção de rastreamento continua revertendo para 30 dias
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.Uma consulta de métrica retorna um resultado vazio
Uma consulta de métrica retorna um resultado vazio
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.Uma fonte de dados do Grafana Prometheus não se conectará
Uma fonte de dados do Grafana Prometheus não se conectará
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.Um coletor recebe 401 em cada exportação
Um coletor recebe 401 em cada exportação
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.

