Skip to main content
Los ejemplos de cliente utilizan CLI v0.13.0 y Go SDK v0.15.0. Consulte Configuración de CLI y Configuración de Go. Los fragmentos de Go asumen un cfg configurado, un ctx de context.Background(), e importaciones para log, basaltic (github.com/basaltic-sh/sdk-go) y telemetry (github.com/basaltic-sh/sdk-go/telemetry). LOG_GROUP_ID / logGroupID es el UUID de grupo de registro devuelto. Vea Resource references para los tipos de referencia aceptados, los ámbitos de búsqueda, las identidades canónicas y los filtros de lista exacta. La telemetría almacena las tres señales de observabilidad que emiten las cargas de trabajo: registros de registro agrupados en grupos de registro, muestras de métricas en un almacén de series temporales y intervalos de traza que se pueden volver a ensamblar en una cascada. Escribes a través de una API JSON nativa, un receptor OTLP o Prometheus remote_write, lo que tu agente existente ya hable. El servicio es regional. Los datos se almacenan en la región en la que se escribieron y no hay lectura entre regiones:

Registros

Crear un grupo, ingresar a él y la ventana de búsqueda que no es opcional.

Métricas

Lo que significa y no significa “compatible con Prometeo” aquí.

Trazas

Ingestión de intervalo, lecturas en cascada y una configuración de retención por cuenta.

OTLP

Apuntando un recopilador hacia nosotros, y la restricción de autenticación que se golpeará primero.
Cada punto final de telemetría se limita a una cuenta. Enviar el identificador de la cuenta en X-Account-Id; sin él la solicitud es rechazada antes de llegar a un controlador. El identificador selecciona la cuenta en la que estás actuando: no es una credencial y la comprobación de IAM se sigue ejecutando en los recursos de esa cuenta.

Registros

Crear primero el grupo de registros

Un grupo de registros es la unidad de retención, cifrado y alcance de IAM. No se pueden escribir registros en un grupo que no existe: una ingesta que nombra un grupo no registrado rechaza ese registro, no lo crea para usted.
Vaya a Telemetry → Log Groups y elija Create Log Group. En Log group details, establezca el Name y una Description opcional; en Retention & encryption, establezca Retention o active Never expire y, opcionalmente, elija una Encryption key. Tags toma etiquetas de clave/valor.El campo Retention aceptará cualquier número entero del 1 al 3650, pero el servicio solo acepta los veintidós valores que se enumeran a continuación. Un número que no es uno de ellos se rechaza cuando lo envía, no mientras lo escribe.
name es 1–512 caracteres de A-Za-z0-9_./#- y es inmutable. Cambiar el nombre de un grupo cambiaría el CRN de todas las referencias de políticas existentes, por lo que un cambio de nombre es una eliminación y una nueva creación.
Un / inicial es rechazado. /app/prod/api no es un nombre de grupo de registro válido — el CRN ya usa / para separar el tipo de recurso del id, por lo que una barra diagonal al principio se representaría como log-group//app/prod/api. Las barras dentro del nombre están bien y se recomiendan.
Los nombres jerárquicos son rentables en IAM. El nombre cae en el CRN literalmente, por lo que una política puede usar comodín en todo un subárbol:

Retención

retention_days acepta uno de veintidós valores, o null para nunca expirar:
El conjunto cerrado no es arbitrariedad por sí mismo. La retención es parte de la clave de partición de almacenamiento, que es lo que permite que la expiración elimine una partición completa en lugar de reescribir una para eliminar filas de corta duración entre las de larga duración. Con los enteros de forma libre, el recuento de particiones se convierte en una función de cuántos números distintos escriben los clientes. Veintidós opciones lo limitaban.
La retención se aplica a los registros a medida que se escriben. Al bajarla solo se alcanzan los registros ingeridos después del cambio; lo que ya está almacenado mantiene la retención con la que fue estampado. Mover un grupo a nunca-caducar después de que tenga un valor limitado requiere un clear explícito — retention_days: null solo no es suficiente.
Abra el grupo desde Telemetry → Log Groups, active Never expire en Settings y elija Save.

Ingestión

log_group, log_stream y body son requeridos por registro. log_group acepta un nombre exacto, UUID o CRN en su cuenta; los CRN deben coincidir con la región de servicio y el identificador de su cuenta. Las referencias no válidas nunca vuelven a otra búsqueda. El mismo contrato se aplica al filtro de búsqueda log_group. Lista los grupos de registro con los filtros exactos name y crn; suministrando ambos los interseca, incluyendo la paginación. Los filtros CRN mal formados o vacíos devuelven 400; los CRN extranjeros válidos o no coincidentes devuelven una página vacía. log_stream es de forma libre y convencionalmente identifica al productor — un host, un contenedor, una tarea. timestamp es opcional y por defecto se usa para ingerir la hora.
Un 202 no significa que todos los registros hayan sido aterrizados. El estado informa que el lote fue aceptado a nivel de cable. Lee accepted, rejected y errors en el cuerpo — un registro que nombra un grupo que no existe, o que falla en la validación, se elimina individualmente mientras el resto del lote fluye:
Dos límites limitan una llamada: como máximo 1000 registros por lote, y un cuerpo de solicitud de 4 MiB.

Las marcas de tiempo que proporcionas están limitadas

Una timestamp proporcionada por el llamador es aceptada solo entre 2000-01-01 y 24 horas adelante del reloj del servidor receptor. La asignación de sesgo cubre un reloj de productor a la deriva y un exportador de lotes.
El límite existe porque la marca de tiempo decide en qué partición de retención cae un registro y cuándo cae la caducidad. Un registro sellado en 2200 se quedaría solo en una partición que no consulta nada y sobreviviría a su ventana de retención por mucho tiempo antes de que se estampara.
Se reservan dos claves de atributo: basaltic_account_id y basaltic_org_id se eliminan de cualquier cosa que envíe y se establecen desde su identidad firmada. Una carga de trabajo con acceso de shell en una de tus instancias no puede etiquetar sus registros como de otra persona.

Búsqueda

from y to son requeridos, y la ventana debe ser de como mucho 31 días — una búsqueda sin límites se convertiría en un análisis de retención completa. Los resultados vuelven más nuevo primero con un cursor opaco marker. trace_id es el más útil cuando ya tienes un rastro: extrae las líneas de registro emitidas dentro de esos intervalos, para que puedas leer los registros de una solicitud y su cascada entre sí.

Eliminar un grupo

Al eliminar, se elimina el registro administrativo del grupo. Los registros de registro ya escritos mantienen su referencia a él y siguen expirando en su propio horario, pero el nombre del grupo ya no se resuelve, por lo que no se puede buscar por grupo después de la eliminación.
En Telemetry → Log Groups, cada fila lleva una acción Delete log group.

Métricas

Qué significa “compatible con Prometheus” aquí

Precisamente dos cosas, y vale la pena tener claro la tercera:

Compatible

Ingest es el verdadero protocolo remote_write — un protobuf WriteRequest comprimido con snappy, byte por byte lo que envía un servidor Prometheus.Los sobres de respuesta son los de Prometheus — status, data.resultType (matrix o vector) y data.result — con valores de muestra como cadenas y marcas de tiempo como segundos unix, por lo que un renderizador de gráficos existente los lee sin cambios.

No es compatible

El lenguaje de consulta no es PromQL. No hay parámetro de expresión query=. Selecciona una métrica, la filtra con etiquetas coincidentes, la agrupa y la agrega a través de parámetros estructurados.Las uniones, histogram_quantile, y expresiones arbitrarias no tienen equivalente aquí. Una fuente de datos de Grafana Prometheus no funcionará con estos puntos finales.

Ingestión

Devuelve 204 en caso de éxito, según la especificación de Prometheus. Cada serie temporal se estampa con su cuenta y organización en el camino, y cualquier etiqueta de inquilino que la carga útil ya haya llevado se elimina primero; un productor no puede reclamar la serie de otra cuenta.

Consulta

Una consulta instantánea devuelve un vector — el agregado sobre una ventana de retrospectiva que termina en time:
Una consulta de rango devuelve una matriz sobre buckets de ancho step:
required
El nombre de la métrica. Una métrica por consulta.
avg | sum | min | max | count | last | rate | increase
Cómo se derrumban las muestras dentro de un bucket. Por defecto a avg cuando se omite. rate y increase derivan de muestras sucesivas de contador y son reset-guardados, por lo que un reinicio del contador no se lee como un pico.
repeated
Etiqueta los coincidentes usando los cuatro operadores de PromQL: =, !=, =~, !~. Por ejemplo match[]=job="api" y match[]=route=~/v1/.*.
repeated
Agrupar por nombres de etiquetas. Omita esta opción y obtendrá una serie por cada conjunto de etiquetas.
duration
Ancho del bucket en query_range (por defecto a 60s, mínimo 1s); ventana de retrospectiva en query (por defecto a 5m).
Cada punto final de consulta también acepta POST con un cuerpo codificado en forma, que es cómo se envía un conjunto de coincidencias demasiado largo para caber en una URL.
Una consulta de rango está limitada a 11 000 puntos. start/end dividido por step Por encima de lo que se rechaza con query yields too many points; widen step or shorten the window En lugar de materializar la matriz. Widen step Primero — es casi siempre la perilla equivocada que se giró.

Discovery

GET /v1/metrics/names?start=…&end=… devuelve los nombres de las métricas que emitiste en la ventana. GET /v1/metrics/series?metric=…&start=…&end=… devuelve los conjuntos de etiquetas distintos para una métrica. Juntos son lo que un creador de paneles necesita para ofrecer un selector en lugar de un campo de texto en blanco.

La retención métrica se fija en 30 días

A diferencia de los registros y las trazas, la retención de métricas no es por inquilino ni configurable: las muestras caducan 30 días después de su marca de tiempo. Es también por eso que la ventana de consulta está limitada a 31 días: una ventana más larga solo podría devolver un rango parcialmente vacío.

Trazas

Intervalos de ingestión

Mismo formato de lote que los registros: hasta 1000 intervalos, 202 con rejected y errors por registro.
Un intervalo necesita un nombre de servicio aunque el esquema de solicitud no lo marque como requerido. Se toma del service_name de nivel superior, o de resource["service.name"] si no está presente. Un intervalo que no lleva ninguno de los dos es rechazado — sin servicio, una traza no puede ser atribuida a nada en el lado de lectura.
trace_id es de 32 caracteres hexadecimales y span_id es de 16, coincidiendo con el formato de cable de OpenTelemetry. parent_span_id está vacío para un rango raíz. end_time no debe preceder a start_time. Las marcas de tiempo de intervalo están delimitadas por la misma ventana de ingesta que los registros. kind por defecto es INTERNAL y status_code es UNSET.

Lectura de trazas

Esto devuelve un resumen por cada traza distinta — operación raíz, servicio raíz, duración, conteo de intervalo, conteo de errores, conteo de servicios — que es la forma en que una lista de trazas se representa sin buscar nada más. GET /v1/traces/{trace_id} entonces devuelve cada intervalo en ese rastro, ordenado por start_time ascendente, por lo que puede ser dibujado como una cascada directamente. El límite de 31 días también se aplica aquí, y se requieren from/to.

Configuración de trazas

La retención de rastreo se establece una vez por cuenta, no por grupo de registros: una configuración decide el destino de todo lo que la cuenta rastrea.
Se aplican los mismos veintidós valores de retención, por la misma razón de partición.
La configuración de seguimiento es solo API. La página de la consola Telemetría → Trazas lee trazas y nada más — no hay control para la retención de intervalos o para los intervalos de claves bajo los cuales se cifran, por lo que un PUT es la única manera de cambiar cualquiera de los dos.
Los intervalos no tienen opción de nunca expirar, y las dos formas en que puedes alcanzar uno te restablecen a la opción predeterminada:
  • clear_retention: true establece la retención de nuevo a 30 días. En un grupo de registros significa nunca expirar; en la configuración de seguimiento no lo hace.
  • Omitir retention_days del cuerpo PUT hace lo mismo — esto es un PUT, así que el cuerpo es la intención completa, y una retención que falta no es “dejarlo en paz”.
Lee la respuesta para confirmar lo que has recibido.
Un rastro es la señal de mayor volumen que acepta la plataforma: una fila por operación, que contiene atributos, eventos y enlaces. El techo, 3653 días, ya está más allá de cualquier horizonte en el que se lee una traza. Al igual que los grupos de registro, un cambio de retención solo alcanza los intervalos ingeridos después de él. Una cuenta que nunca ha escrito la configuración lee el valor predeterminado de 30 días, que es exactamente con lo que se están marcando sus intervalos.
No hay control de muestreo del lado del servidor. La configuración de seguimiento cubre la retención y la asociación de claves, nada más: la API almacena cada intervalo que envía. Muestree en su SDK o recopilador, antes de que los datos abandonen su carga de trabajo.

Cifrado en reposo

Un grupo de registro y la configuración de seguimiento de una cuenta toman una kms_key opcional. Cuando se establece una clave, los cuerpos de registro (y, para los intervalos, el bolso de nombre, mensaje de estado, atributos, eventos y enlaces escritos por el cliente) se cifran en sobre con esa clave antes de almacenarlos. Utilice su UUID, CRN o nombre exacto en su cuenta y región. El enlace almacena su UUID, por lo que eliminar una clave y volver a crear su nombre no puede volver a asignar los datos almacenados. Omitir kms_key en una actualización de log-group preserva el enlace; trace-settings PUT reemplaza la configuración, por lo que la omisión restablece el cifrado. kms_key_unavailable informa de una clave enlazada cuyos metadatos no están disponibles; no significa texto plano. Los campos indexados permanecen en claro para que la búsqueda siga funcionando sin desenroscar nada: para los intervalos que son service_name, trace_id, span_id, timing y status_code.
La asociación o desasociación de una clave solo afecta a los datos ingeridos después del cambio. Los registros ya almacenados mantienen cualquier estado de cifrado con el que se escribieron. Pasa una cadena vacía para desasociar.
La clave de un grupo de registros se puede configurar en la consola: Encryption key en Create Log Group, o en Settings de un grupo existente seguido de Save. La asociación del lado del rango vive en la configuración de seguimiento, que no tiene página de consola, por lo que solo es API.

OTLP

El receptor OTLP es un host separado que sirve las rutas canónicas de OpenTelemetry, por lo que un SDK las resuelve desde una variable:
Solo protobuf binario. Content-Type debe ser application/x-protobuf; la codificación de protobuf JSON se rechaza. Establezca OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf, no http/json.
Los rechazos regresan en el propio sobre partial_success de OTLP con un recuento de rejected_log_records y un mensaje de error unido, en lugar de como un error HTTP — la misma semántica por registro que la ingesta nativa, expresada en la forma del protocolo.

Resolución del grupo de registros

OTLP no tiene un concepto de grupo de log, por lo que el receptor deriva uno de los atributos de recursos: Tanto en HTTP como en gRPC, cualquier selector acepta un nombre de grupo de registro exacto, UUID o CRN. Se conserva el nombre completo con barra diagonal. El grupo resuelto debe seguir existiendo en la cuenta. Crea el registro antes de apuntar un colector al receptor, o todos los registros serán rechazados. La severidad usa severity_text cuando el SDK establece uno; de lo contrario, las bandas numéricas se asignan según la especificación de OpenTelemetry: 1-4 TRACE, 5-8 DEBUG, 9-12 INFO, 13-16 WARN, 17-20 ERROR, 21-24 FATAL.

Autenticación

OTLP sobre HTTP y gRPC acepta un token portador OAuth, con la cuenta seleccionada en X-Account-Id. Use Authorization: Bearer <access_token> para HTTP, o metadatos gRPC equivalentes en minúsculas. La cuenta debe coincidir con la cuenta de servicio o sesión de rol que emitió el token. Configure el recopilador para que actualice el token antes de que caduque. Un token caducado incrustado permanentemente en la configuración del exportador dejará de funcionar. La misma autenticación de portador se aplica a POST /v1/metrics/write. Consulte authentication para intercambio de credenciales y sesiones de rol.

Permisos

Las acciones de telemetría autorizan contra el CRN de la cosa que se está tocando, por lo que una política puede ser de ámbito a un grupo o una convención de nombres. Consulte policies para saber cómo funciona la evaluación. Un lote que toca varios grupos de registros se autoriza por grupo. Un grupo denegado solo falla sus propios registros, el resto del lote se escribe.

Límites

1000 records
Por POST /v1/logs y por POST /v1/spans.
4 MiB
Tanto en la API nativa como en el receptor OTLP.
31 days
Requerido y limitado en GET /v1/logs, GET /v1/traces, y cada consulta de métrica.
11 000
(end - start) / step en query_range.
2000-01-01 to now + 24h
Se aplica a las marcas de tiempo de registro y al intervalo start_time / end_time.
30 days
Corregido. La retención de registros y seguimiento es suya para elegir.

Solución de problemas

Lee rejected y errors en el cuerpo 202. La entrada más común es un grupo de registro que nunca se creó: ingest es estricto y nombrar un grupo desconocido rechaza ese registro en lugar de crear el grupo.El segundo más común es una marca de tiempo fuera de la ventana aceptada. Comprueba el reloj del productor: cualquier cosa que esté más de 24 horas por delante del nuestro se elimina por registro.
Los nombres no pueden comenzar con /. app/prod/api es válido; /app/prod/api no lo es. Las barras en otras partes del nombre están bien.La regla completa es de 1-512 caracteres de A-Za-z0-9_./#-, y el primer carácter no puede ser /.
La retención es un conjunto cerrado, no un rango: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653. Un valor como 45 o 3650 se rechaza incluso si cae entre entradas válidas.
PUT /v1/trace-settings reemplaza todo el documento de configuración. Omitir retention_days — o enviar clear_retention: true esperando que nunca caduque — restablece el valor predeterminado de 30 días, porque los intervalos no tienen opción de nunca caducidad.Envía la retención que deseas en cada PUT, y lee la respuesta de vuelta.
Confirme el nombre de la métrica con GET /v1/metrics/names para la misma ventana — un nombre que nunca se emitió devuelve éxito con un resultado vacío, no un error. Luego compruebe el conjunto de etiquetas con GET /v1/metrics/series: un matcher contra una etiqueta que la serie no lleva filtra todo.También revise la ventana contra la retención. Las métricas caducan después de 30 días, por lo que una consulta cerca del límite de 31 días puede estar leyendo más de los datos.
No puede. Los puntos finales de lectura comparten el sobre de respuesta de Prometheus pero no su lenguaje de consulta o su diseño de URL — no hay parámetro /api/v1/query ni query=<promql>, y usan el flujo de autenticación de portador de plataforma.Ingest es la mitad compatible: remote_write de Prometheus o un agente funciona con un token de portador válido y un encabezado de cuenta.
Compruebe la caducidad del token del portador, la vinculación de cuentas y los permisos de telemetría. Enviar Authorization: Bearer <token> y X-Account-Id. Actualice los tokens caducados a través del punto final de OAuth; no se aceptan firmas de solicitud heredadas.

Siguiente

Autenticación

El procedimiento de firma que necesita cada solicitud de ingesta y consulta.

Políticas

Ámbito de una directiva a un subárbol de grupo de registro.

Regiones

Qué host llamar y por qué la telemetría es regional.

Referencia de la API

Todas las operaciones de telemetría, con esquemas de solicitud y respuesta.