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.- Console
- API
- CLI
- Go
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.
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.
retention_days: null solo no es suficiente.
- Console
- API
- CLI
- Go
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.
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
Unatimestamp 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.
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.- Console
- API
- CLI
- Go
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
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 entime:
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).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.
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
202 con rejected y errors por registro.
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
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.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.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 unakms_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 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:
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 enX-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
Ingest devuelve 202 pero no se puede buscar nada
Ingest devuelve 202 pero no se puede buscar nada
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.La creación de un grupo de registro devuelve 400 en el nombre
La creación de un grupo de registro devuelve 400 en el nombre
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 /.retention_days es rechazado
retention_days es rechazado
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.
La retención de rastros sigue revertiendo a 30 días
La retención de rastros sigue revertiendo a 30 días
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.Una consulta de métrica devuelve un resultado vacío
Una consulta de métrica devuelve un resultado vacío
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.Una fuente de datos de Grafana Prometheus no se conectará
Una fuente de datos de Grafana Prometheus no se conectará
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.Un coleccionista obtiene 401 en cada exportación
Un coleccionista obtiene 401 en cada exportación
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.

