Documentação do Oracle Cloud Infrastructure

Publicando Métricas Personalizadas Usando a API

Publique métricas personalizadas no serviço Monitoring.

Dica

Configurações do agente são outra maneira de publicar métricas personalizadas no Monitoring. Com as configurações do agente, a API não é necessariamente necessária para publicar métricas personalizadas. Agora você pode usar configurações de agente para ingerir dados de métrica em métricas personalizadas. Por exemplo, exponha métricas de uma máquina virtual (VM) usando um ponto final HTTP no formato Prometheus.

Uma métrica personalizada é uma métrica projetada para coletar e analisar dados.

Por exemplo, crie uma métrica productOrder (em um namespace de métrica, mymetricsnamespace) para rastrear ordens de produto por país e divisão, com metadados adicionais para categorias e observações de produto.

Antes de Iniciar

Políticas do Serviço IAM: Para publicar métricas personalizadas, você deve ter o tipo necessário de acesso em uma política  gravada por um administrador. Esse requisito será aplicável se você estiver usando a API REST com um SDK, uma CLI ou outra ferramenta. Se você receber uma mensagem de que não tem permissão ou que não está autorizado, verifique com o administrador. Talvez você não tenha o tipo obrigatório de acesso no compartimento  atual.

Administradores: Para obter um exemplo de política, consulte Publicar Métricas Personalizadas (Protegendo o Monitoramento).

Considerações

Ao definir métricas personalizadas, observe o seguinte:

  • Para o namespace de métrica, não use um prefixo reservado (oci_ ou oracle_).
  • Certifique-se de que as métricas personalizadas não excedam os limites. Por exemplo, observe o intervalo válido de dimensões e o número máximo de streams para métricas personalizadas. Consulte PostMetricData.
  • Defina métricas com agregação em mente. Embora as métricas personalizadas possam ser publicadas com tanta frequência quanto a cada segundo (frequência mínima de um segundo), o intervalo mínimo de agregação é de um minuto.
  • Defina métricas com limites de retorno em mente. As informações de limites para os dados retornados incluem o máximo de 100.000 pontos de dados e os máximos de intervalo de tempo (determinados pela resolução, relacionada ao intervalo).. Consulte MetricData. Consulte também Limites de Monitoramento.
  • Certifique-se de que os valores de timestamp estejam próximos do horário atual. Para que um ponto de dados seja postado, seu timestamp deve estar próximo ao horário atual (há menos de duas horas e passando menos de 10 minutos). Consulte PostMetricData.
  • Após publicar métricas personalizadas, você pode acessá-las da mesma forma que acessa qualquer outra métrica armazenada pelo serviço Monitoring: Exibir gráficos na Console, consultar métricas usando a CLI ou a API e criar alarmes.
  • Ao recuperar métricas personalizadas, você pode corresponder a um grupo de recursos. Em branco (nulo) para o grupo de recursos retorna dados de métrica que não têm um grupo de recursos.
  • Essa tarefa não pode ser executada na Console.
  • Observação

    Ao contrário de outros comandos do serviço Monitoring que usam pontos finais telemetry, esse comando exige um ponto final telemetry-ingestion.

    Use o comando oci monitoring métrica-data post, o parâmetro --endpoint e os parâmetros obrigatórios para publicar métricas personalizadas:

    oci monitoring metric-data post --metric-data <json_file_path> --endpoint https://telemetry-ingestion.<region>.oraclecloud.com

    Para obter uma lista completa de parâmetros e valores para comandos da CLI, consulte a Referência de Linha de Comando para o Serviço Monitoring.

    Exemplo de arquivo JSON para solicitação

    O arquivo JSON de exemplo inclui os itens a seguir.

    • Namespace da métrica: mymetricsnamespace
    • Nome da métrica: productOrder
    • Dimensão do produto
    • Dimensão do país
    • Grupo de recursos (DivisionX, DivisionY)
    • Metadados adicionais para categoria e observação
    [
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 10,
        "timestamp": "2023-01-08T04:18:01+00:00",
        "value": 5.0
      },
      {
        "count": 3,
        "timestamp": "2023-01-08T05:11:01+00:00",
        "value": 10.0
      }
    ],
    "dimensions": {
      "product": "ball",
      "country": "NL"
    },
    "metadata": {
      "category": "toys",
      "note": "national holiday"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionX"
  },
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 7,
        "timestamp": "2023-01-08T03:22:01+00:00",
        "value": 3.0
      },
      {
        "count": 11,
        "timestamp": "2023-01-08T05:08:03+00:00",
        "value": 2
      }
    ],
    "dimensions": {
      "product": "The Road to Nowhere",
      "country": "FR"
    },
    "metadata": {
      "category": "books",
      "note": "start second semester"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionY"
  }
]
    Exemplo de resposta
    {
  "data": {
    "failed-metrics": [],
    "failed-metrics-count": 0
  }
}
  • Observação

    Ao contrário de outras operações do serviço Monitoring que usam pontos finais telemetry, essa operação exige um ponto final telemetry-ingestion.

    Execute a operação PostMetricData para publicar métricas personalizadas.

    Exemplo de uma solicitação em batch

    Este exemplo mostra uma única solicitação contendo pontos de dados para métricas em dois namespaces de métricas . 

    [
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"myFirstResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:20Z",
            "value":83.0
         },
         {
            "timestamp":"2023-01-10T22:19:40Z",
            "value":90.1
         }
      ]
   },
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"mySecondResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.differentuniqId",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:10Z",
            "value":100.0
         },
         {
            "timestamp":"2023-01-10T22:19:30Z",
            "value":100.0
         }
      ]
   },
   {
      "namespace":"mySecondNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "name":"deliveryRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppB"
      },
      "metadata":{
         "unit":"bytes",
         "displayName":"MyAppB Delivery Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:00Z",
            "value":87.0,
            "count":60
         },
         {
            "timestamp":"2023-01-10T22:19:00Z",
            "value":96.0,
            "count":30
         }
      ]
   }
]