> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Criar um alerta de métrica > Cria uma delegação persistente para leitura de métricas e publicação de notificações. Requer telemetry:CreateAlert no alerta nomeado, telemetry:ReadMetrics na conta e notifications:Publish no tópico selecionado. As transições de disparo e resolução usam as assinaturas confirmadas de e-mail, webhook e fila do tópico. Os eventos são armazenados atomicamente com as alterações de estado e reenviados com IDs de mensagem estáveis. Dados ausentes e erros de avaliação são estados visíveis, não notificações de recuperação. ## OpenAPI ````yaml /pt/api-reference/specs/telemetry.yaml post /v1/alerts openapi: 3.0.3 info: title: API de Telemetria Basaltica version: 1.0.0 description: > API regional de telemetria: grupos de logs, ingestão e pesquisa de logs, ingestão remote_write, consultas estruturadas de métricas em JSON, spans, pesquisa e detalhes de rastros e configurações por conta. Referências de grupos de logs aceitam UUID, CRN ou nome exato na conta, classificados pela sintaxe sem busca alternativa. CRNs devem corresponder à conta autenticada e à região. Logs OTLP HTTP e gRPC usam basaltic.log_group ou service.name com o mesmo contrato. Identificadores de rastros e spans, rótulos de métricas e regiões de pesquisa são valores de protocolo independentes da resolução de recursos. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://telemetry.{region}.basaltic.sh description: Endpoint de API regional (um por região) variables: region: default: sa-saopaulo-1 description: Código de região security: - BearerAuth: [] paths: /v1/alerts: post: tags: - Telemetry summary: Criar um alerta de métrica description: >- Cria uma delegação persistente para leitura de métricas e publicação de notificações. Requer telemetry:CreateAlert no alerta nomeado, telemetry:ReadMetrics na conta e notifications:Publish no tópico selecionado. As transições de disparo e resolução usam as assinaturas confirmadas de e-mail, webhook e fila do tópico. Os eventos são armazenados atomicamente com as alterações de estado e reenviados com IDs de mensagem estáveis. Dados ausentes e erros de avaliação são estados visíveis, não notificações de recuperação. operationId: createAlert parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAlertRequest' responses: '201': description: Criar um alerta de métrica content: application/json: schema: $ref: '#/components/schemas/AlertResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Chave opcional gerada pelo cliente que torna uma criação segura para reprodução. A reintentar uma solicitação com a mesma chave retorna o resultado original literalmente em vez de criar um recurso duplicado. A reutilização de uma chave com um corpo de solicitação diferente é rejeitada (422); uma solicitação cuja chave ainda está sendo processada retorna 409. Os registros são honrados por 24 horas. Use um UUID ou token exclusivo semelhante. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateAlertRequest: type: object additionalProperties: false required: - name - topic - expression - operator - threshold - window_seconds - for_seconds properties: name: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$ description: >- Nome imutável e exclusivo na conta. Nomes UUID e o prefixo crn: são reservados. topic: type: string description: >- Referência obrigatória a um tópico de notificação da mesma conta e região: UUID, CRN canônico ou nome exato, classificado pela sintaxe. Vários alertas podem compartilhar um tópico. A vinculação requer notifications:Publish e respeita negações explícitas da política do tópico. expression: $ref: '#/components/schemas/AlertExpression' operator: type: string enum: - gt - gte - lt - lte threshold: type: number format: double window_seconds: type: integer minimum: 60 maximum: 3600 multipleOf: 60 description: >- Janela de minutos inteiros. Avaliada a cada minuto usando a última janela completa alinhada ao UTC. for_seconds: type: integer minimum: 0 maximum: 86400 multipleOf: 60 description: >- Duração contínua da violação antes do disparo; 0 dispara imediatamente. Dados ausentes, falhas de consulta e intervalos sem avaliação reiniciam a duração pendente. enabled: type: boolean default: true silenced_until: type: string format: date-time nullable: true description: >- Silencia as notificações até este instante (no máximo 30 dias no futuro). A avaliação continua; null remove o silenciamento. Um alerta ativo notifica na próxima avaliação após o fim do silenciamento. AlertResponse: type: object required: - alert properties: alert: $ref: '#/components/schemas/Alert' AlertExpression: type: object additionalProperties: false required: - metric - agg - scale properties: metric: type: string maxLength: 256 pattern: ^[a-zA-Z_:][a-zA-Z0-9_:]*$ agg: type: string enum: - avg - min - max - sum - last - count - rate - increase match: type: array maxItems: 40 items: type: string description: >- Filtros de rótulo (label=value, label!=value, label=~regex, label!~regex). O escopo do locatário é sempre aplicado de forma independente. by: type: array maxItems: 10 items: type: string description: >- Rótulos de agrupamento; as séries resultantes são somadas para corresponder ao cartão de métrica do console. denominator: $ref: '#/components/schemas/AlertQuery' scale: type: number format: double minimum: 0 exclusiveMinimum: true maximum: 1000000000000 description: >- Multiplicador após a divisão opcional, por exemplo, 100 para porcentagem ou 1/1048576 para MiB/s. unit: type: string maxLength: 32 description: Unidade de exibição do limite e do valor após a aplicação da escala. Alert: type: object required: - id - crn - name - topic - expression - operator - threshold - window_seconds - for_seconds - enabled - silenced_until - state - last_value - created_at - updated_at properties: expression: $ref: '#/components/schemas/AlertExpression' operator: type: string enum: - gt - gte - lt - lte threshold: type: number format: double window_seconds: type: integer minimum: 60 maximum: 3600 multipleOf: 60 description: >- Janela de minutos inteiros. Avaliada a cada minuto usando a última janela completa alinhada ao UTC. for_seconds: type: integer minimum: 0 maximum: 86400 multipleOf: 60 description: >- Duração contínua da violação antes do disparo; 0 dispara imediatamente. Dados ausentes, falhas de consulta e intervalos sem avaliação reiniciam a duração pendente. enabled: type: boolean default: true silenced_until: type: string format: date-time nullable: true description: >- Silencia as notificações até este instante (no máximo 30 dias no futuro). A avaliação continua; null remove o silenciamento. Um alerta ativo notifica na próxima avaliação após o fim do silenciamento. id: type: string format: uuid crn: type: string example: crn:telemetry:sa-saopaulo-1:my-account:alert/high-cpu name: type: string topic: $ref: '#/components/schemas/ResourceRef' state: type: string enum: - ok - pending - firing - no_data - error description: >- Estado de avaliação, independente de enabled e silenced_until. Dados ausentes ou erros não resolvem um incidente aberto. last_value: type: number format: double nullable: true evaluated_at: type: string format: date-time state_changed_at: type: string format: date-time pending_since: type: string format: date-time evaluation_error: type: string delivery_error: type: string description: >- A notificação permanece na fila para nova tentativa; a avaliação da métrica continua. created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de erro identificando o tipo de erro example: INVALID_INPUT message: type: string description: Mensagem de erro legível pelo ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores não sensíveis opcionais para interpolação de erros localizados, codificados por código de erro. Nunca presente para erros de servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuração example: 550e8400-e29b-41d4-a716-446655440000 AlertQuery: type: object additionalProperties: false required: - metric - agg properties: metric: type: string maxLength: 256 pattern: ^[a-zA-Z_:][a-zA-Z0-9_:]*$ agg: type: string enum: - avg - min - max - sum - last - count - rate - increase match: type: array maxItems: 40 items: type: string description: >- Filtros de rótulo (label=value, label!=value, label=~regex, label!~regex). O escopo do locatário é sempre aplicado de forma independente. by: type: array maxItems: 10 items: type: string description: >- Rótulos de agrupamento; as séries resultantes são somadas para corresponder ao cartão de métrica do console. ResourceRef: type: object required: - id - crn properties: id: type: string format: uuid example: 288aa1e9-bbf5-5584-bce9-6a688f06d8a1 crn: type: string example: crn:catalog::platform:country/288aa1e9-bbf5-5584-bce9-6a688f06d8a1 name: type: string description: >- Rótulo no momento da resposta: o nome do recurso, quando houver, ou seu rótulo legível (número de fatura, nome de exibição da conta). Ausente quando o destino não existe mais. Não é uma chave de consulta. example: Brazil responses: BadRequest: description: Parâmetros de solicitação inválidos content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Autenticação necessária ou token inválido content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Permissões insuficientes content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Página não encontrada content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 Conflict: description: Conflito de recursos (por exemplo, já existe, estado inválido) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: Resource with this name already exists request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Erro interno do servidor content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `. Esta é a forma recomendada de autenticação. Obtenha o token trocando o par de chaves de acesso de uma conta de serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`. Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis com OAuth podem obter e renovar o token para você. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso também serve como credencial AWS SigV4 para o endpoint de objetos compatível com S3, que aceita somente esse método de autenticação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.