Envoyez un événement personnalisé avec notre API événement

L'API événement vous permet d'envoyer des données d'événement personnalisées à New Relic. Ces événements peuvent ensuite être interrogés et cartographiés.

Vous souhaitez tester notre API événement ? Créez un compte New Relic gratuitement ! Aucune carte de crédit requise.

Contenu connexe :

• Découvrez toutes les options de reporting d'événement personnalisé.
• Pour savoir comment ajouter un attribut à un événement existant, voir Ajouter un attribut personnalisé.

Pourquoi utiliser l'API événement ?

Notre API d'événement est une option permettant de générer des rapports de données personnalisées. Une autre option consiste à signaler l'attribut personnalisé. Pour un aperçu des raisons pour lesquelles vous utiliseriez l'API événement par rapport à d'autres options, consultez événement personnalisé et attribut.

Exigences

Pour les limites de l'API événement et les attributs restreints, voir Limites.

Assurez-vous que la connectivité sortante sur le port TCP 443 est autorisée sur la plage CIDR qui correspond à votre région. La méthode de configuration préférée consiste à utiliser le nom DNS insights-collector.newrelic.com ou insights-collector.eu01.nr-data.net.

Exemple de soumission et d'interrogation d'un événement personnalisé

Voici un exemple de l'API événement en action :

# Hook into the runtime 'at_exit' event
at_exit do
  # Name the custom event
  payload = { 'eventType' => 'CLIRun' }

  # Check to see if the process is exiting due to an error
  if $!.nil? || $!.is_a?(SystemExit) && $!.success?
    payload[:status] = 0
  else
    # Gather any known errors
    errors = ""
    (Thread.current[:errors] ||= []).each do |err|
      errors += "#{err}\n"
    end
    payload[:errors] = errors
  end

  # Send the errors to New Relic as a custom event
  insights_url = URI.parse("https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/events")
  headers = { "Api-Key" => "YOUR_LICENSE_KEY", "content-type" => "application/json" }

  http = Net::HTTP.new(insights_url.host, insights_url.port)
  http.use_ssl = true
  request = Net::HTTP::Post.new(insights_url.request_uri, headers)
  request.body = payload.to_json

  puts "Sending run summary to New Relic: #{payload.to_json}"
  begin
    response = http.request(request)
    puts "Response from New Relic: #{response.body}"
  rescue Exception => e
    puts "There was an error posting to New Relic. Error: #{e.inspect}"
  end
end

SELECT count(*) FROM CLIRun FACET errors SINCE 1 week ago

Comment utiliser l'API événement

L'API événement est un point de terminaison asynchrone. Cela vous permet d'envoyer un très grand volume de POSTS, de manière fiable, avec une latence de réponse très faible.

Pour envoyer un événement personnalisé à un compte New Relic :

1. Obtenez un clé de licencepour le compte auquel vous souhaitez signaler des données.
2. Avant de créer un événement personnalisé ou un attribut, consultez notre liste de termes réservés utilisés par NRQL.
3. Générez du JSON pour l'événement en instrumentant votre application, en interrogeant une API ou une autre méthode.
4. Soumettez une charge utile JSON compressée (par exemple, gzip ou deflate) au point de terminaison HTTPS à l'aide de curl dans une requête POST .
5. Recommandation : Configurez la condition d'alerte NRQL pour vous avertir lorsque des erreurs d'analyse se produisent.

L'API événement limite la taille, le débit et les caractères autorisés dans événement personnalisé. De plus, comme d’autres données disponibles dans NRQL, les événements personnalisés ne peuvent pas être mis à jour ou supprimés après leur création. Si vous rencontrez des problèmes avec votre événement personnalisé, suivez les procédures de dépannage ou créez un nouvel événement personnalisé.

Formater le JSON

L'API événement accepte des formats spécifiques pour les attributs inclus dans la charge. Seules les valeurs flottantes ou de chaîne sont autorisées.

[
  {
    "eventType": "Purchase",
    "account": 3,
    "amount": 259.54
  },
  {
    "eventType": "Purchase",
    "account": 5,
    "amount": 12309,
    "product": "Item"
  }
]

Soumettre l'événement personnalisé

Les données soumises à l'API événement utilisent un format JSON compressé dans une simple requête HTTPS POST. Cet exemple utilise gzip, mais vous pouvez également utiliser deflate.

$
gzip -c example_events.json | curl -X POST -H "Content-Type: application/json" \
>
-H "Api-Key: YOUR_LICENSE_KEY" -H "Content-Encoding: gzip" \
>
https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/events --data-binary @-

$accountId = "YOUR_ACCOUNT_ID"
$insertkey = "YOUR_LICENSE_KEY"
# Replace with your custom event for the body
$body = '[{"eventType": "powershell", "account": 4, "amount": 123, "fileLocation": "c:\\temp2", "zipped": "true" }]'

$headers = @{}
$headers.Add("Api-Key", "$insertkey")
$headers.Add("Content-Encoding", "gzip")


$encoding = [System.Text.Encoding]::UTF8
$enc_data = $encoding.GetBytes($body)

$output = [System.IO.MemoryStream]::new()
$gzipStream = New-Object System.IO.Compression.GzipStream $output, ([IO.Compression.CompressionMode]::Compress)

$gzipStream.Write($enc_data, 0, $enc_data.Length)
$gzipStream.Close()
$gzipBody = $output.ToArray()

Invoke-WebRequest -Headers $headers -Method Post -Body $gzipBody  "https://insights-collector.newrelic.com/v1/accounts/$accountId/events"

Avant de générer votre requête HTTP, assurez-vous qu'elle est correctement formatée, notamment :

• Le Api-Key contient le clé de licencecorrect.
• Le Content-Type est application/json.
• La requête utilise uniquement POST. L'API n'accepte pas les requêtes PUT et GET.

L'API prend en charge les connexions persistantes HTTP/1.1. Cela est utile pour gérer les performances côté client sous de lourdes charges d'événements.

Vérifier ou résoudre la réponse à la demande

L'API événement suit un processus en deux étapes pour traiter requests:

1. L'API événement reconnaît ou rejette de manière synchrone la demande en fonction de la validation des en-têtes et du montant de la charge.
2. L'API événement analyse de manière asynchrone la charge après qu'une réponse HTTP réussie a été fournie au client. Cela peut générer une erreur en raison de données manquantes ou mal formées. Celles-ci sont classées comme des erreurs de soumission ou des erreurs d’analyse.

Toutes les soumissions réussies reçoivent une réponse 200, quelles que soient les erreurs de données pouvant exister dans la charge utile. La réponse inclut un uuid, qui est un identifiant unique créé pour chaque demande. Le uuid apparaît également dans tout événement d’erreur créé pour la demande.

Autres problèmes potentiels :

• Délai d'expiration de 10 secondes : l'appel d'API dépassant 10 secondes expirera.
• Charge importante : une charge supérieure à 100 Ko peut entraîner une augmentation des temps de réponse.

Recommandation : en plus de vérifier un message de réussite, créez une requête NRQL de vos données pour vérifier qu'elles sont disponibles.

{ "success": true, "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

requête et alerte avec NrIntegrationError

L' événementNrIntegrationError vous permet d'interroger et de définir alertessur les données personnalisées envoyées à votre compte New Relic. Recommandation : pour obtenir des alertes en cas d’erreurs d’analyse, créez une condition d’alerte NRQL pour NrIntegrationError. Utilisez cet exemple de requête NRQL :

SELECT message FROM NrIntegrationError WHERE newRelicFeature = 'Event API' AND category = 'EventApiException'

Trouvez vos données

Pour trouver les données envoyées via l'API événement (et depuis les intégrations qui utilisent cette API), vous pouvez l'interroger. Par exemple, pour requêter un événement personnalisé en utilisant NRQL, vous exécuterez :

SELECT * FROM YOUR_CUSTOM_EVENT

Pour en savoir plus sur la façon d'effectuer une requête, voir requête data.

Limite des requestsHTTP

L'API événement a une limite de débit de 100 000 requests HTTP (POST) par minute et par compte. (Notez qu'il ne s'agit pas d'une limite sur le nombre d'événements par minute ; uniquement sur le nombre de POST par minute.)

Cette limite permet de garantir que les pics de trafic importants sur les comptes de notre plateforme multi-locataire n'affectent pas négativement les performances du service pour vous.

Si votre utilisation de l'API dépasse 100 000 POST dans une fenêtre d'une minute, nous rejetterons requests d'API ultérieures avec un code de réponse 429 pour le reste de la fenêtre d'une minute. À la fin de la fenêtre d'une minute, le compteur sera réinitialisé et permettra la reprise du trafic.

Cette limite est destinée à être un seuil supérieur que vous ne devriez pas atteindre dans des scénarios normaux. Si vous avez un nombre élevé de réponses 429, envisagez d'utiliser moins l'API. Si vous prévoyez un niveau d'activité supérieur à la normale dans un avenir proche et que vous souhaitez vous y préparer, contactez le support technique.