For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/fr/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/fr/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/fr/guides/manage-and-operate/observability/logs-data-platform/ldp-index.md.

Input mutualisé - API OpenSearch

Voir en Markdown

Envoyez vos logs vers la plateforme avec l'API OpenSearch.

Vue d'ensemble

OpenSearch est le composant vedette de notre plateforme, il permet d'utiliser des index OpenSearch pour stocker vos documents. Les index OpenSearch sont très flexibles, mais ils ne font pas partie du pipeline de logs. Si vous souhaitez également utiliser le live-tail WebSocket, le système d'alerting ou la fonctionnalité de stockage à froid, et bénéficier d'une gestion automatique de la rétention, vous devrez utiliser le pipeline de logs. Grâce à notre endpoint de logs OpenSearch, vous pourrez envoyer des logs à l'aide de l'API HTTP OpenSearch. De plus, l'endpoint prend également en charge OpenSearch Ingest, ce qui signifie que vous pouvez appliquer un traitement avancé à vos logs avant leur envoi dans le pipeline. Cette fonctionnalité n'entraîne aucun coût supplémentaire ; il vous suffit de disposer d'un flux.

Endpoint OpenSearch

L'endpoint OpenSearch est un index dédié auquel vous pouvez envoyer un document JSON. Le port utilisé est le 9200, le même port HTTP utilisé pour toutes les autres API OpenSearch de Logs Data Platform. La requête doit inclure le champ X‑OVH‑TOKEN, un jeton utilisé par le pipeline de logs, ainsi que tout champ personnalisé supplémentaire. L'authentification de l'endpoint s'effectue via un couple identifiant/mot de passe classique (ou un jeton legacy) pour les utilisateurs non-IAM, ou via un jeton Bearer IAM lorsque IAM est activé. N'hésitez pas à consulter la documentation de démarrage rapide si cette notion ne vous est pas familière. Ce log de document sera transformé en un log GELF valide, et tout champ manquant sera rempli automatiquement. Afin de respecter la convention GELF, vous pouvez également utiliser tous les champs réservés du format GELF. Voici un exemple de message minimal que vous pouvez envoyer :

$ curl -H 'Content-Type: application/json' -u '<user>:<password>' -XPOST https://<ldp-cluster>.logs.ovh.com:9200/ldp-logs/_doc -d '{ "X-OVH-TOKEN" : "7f00cc33-1a7a-4464-830f-91be90dcc880" , "test_field" : "OVHcloud"}'

ou avec IAM activé

$ curl -H 'Content-Type: application/json' --oauth2-bearer '<YOUR_IAM_TOKEN>' -XPOST https://<ldp-cluster>.logs.ovh.com:9200/ldp-logs/_doc -d '{ "X-OVH-TOKEN" : "7f00cc33-1a7a-4464-830f-91be90dcc880" , "test_field" : "OVHcloud"}'

Remplacez <user>, <password> et <ldp-cluster> par votre nom d'utilisateur, votre mot de passe et votre cluster Logs Data Platform. Vous pouvez également utiliser des jetons à la place de vos identifiants. L'envoi de ce payload produira ce log :

simple\_log

Le système a automatiquement défini le timestamp à la date de réception du log et a ajouté le champ test_field au message de log. La source a été définie sur unknown et le message sur -. Notez que le payload respecte la spécification JSON (et non celle du GELF). Le système reconnaîtra tout de même tout champ réservé utilisé par la spécification GELF. Voici un autre exemple :

$ curl -H 'Content-Type: application/json' -u '`<user>`:<password>' -XPOST https://`<ldp-cluster>`.logs.ovh.com:9200/ldp-logs/_doc -d '{ "X-OVH-TOKEN" : "7f00cc33-1a7a-4464-830f-91be90dcc880" , "test_field" : "OVHcloud" , "short_message" : "Hello OS input", "host" : "OVHcloud_doc" }'

Cela créera le log suivant :

gelf\_log

Le système a utilisé les champs réservés associés au GELF pour créer les champs message et source.

Logs Data Platform détectera également tout champ typé dans les données d'origine et les convertira conformément à notre convention de nommage des champs. Ce dernier exemple l'illustre :

$ curl -H 'Content-Type: application/json' -u '`<user>`:<password>' -XPOST https://`<ldp-cluster>`.logs.ovh.com:9200/ldp-logs/_doc -d '{ "X-OVH-TOKEN" : "7f00cc33-1a7a-4464-830f-91be90dcc880" , "test_field" : "OVHcloud" , "short_message" : "Hello OS input", "host" : "OVHcloud_doc", "numeric_field" : 43.5  }'

Le champ numérique numeric_field sera détecté comme un nombre et se verra ajouter un suffixe pour respecter nos conventions de nommage.

gelf\_convention

L'input OpenSearch aplatira également tout sous-objet ou tableau qui lui est envoyé, et prend aussi en charge les pipelines d'ingestion utilisés, par exemple, avec les intégrations Filebeat.

Utiliser l'API OpenSearch avec IAM activé

Lorsque IAM est activé pour votre service Logs Data Platform, la méthode d'authentification de l'API OpenSearch change :

  • L'authentification legacy (non-IAM) utilise un couple identifiant/mot de passe classique (ou un jeton legacy) comme décrit dans les exemples précédents.
  • L'authentification IAM utilise un jeton Bearer obtenu depuis l'IAM OVHcloud (Personal Access Token ou jeton de compte de service).

Comment obtenir un jeton Bearer : vous pouvez en générer un via un compte de service ou un utilisateur local :

Pour un compte de service :

  • Créez un compte de service et attribuez-lui les politiques IAM requises (voir le guide de gestion des accès IAM).

  • Récupérez un jeton d'API à l'aide du workflow OAuth2 client-credentials, comme décrit dans le guide d'authentification par compte de service. La requête ressemble à ceci :

    curl --request POST \
     --url 'https://www.ovh.com/auth/oauth2/token' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data client_id=<service_account_id \
     --data client_secret=`<service_account_secret>` \
     --data scope=all

    La réponse contient un champ access_token : c'est le jeton Bearer à utiliser.

Pour un utilisateur local :

  • Vous pouvez créer un utilisateur local en suivant la section dédiée du guide de gestion des identités.
  • Vous pouvez générer un Personal Access Token via l'API IAM. Consultez la documentation FAQ ou utilisez l'appel :
POST/me/identity/user/{user}/token

Remplacez {user} par votre utilisateur local OVHcloud. La réponse renvoie également un access_token utilisable comme jeton Bearer.

Nouveau format de requête

# Envoyer un log avec IAM (jeton Bearer dans l'en-tête)
curl -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <YOUR_IAM_TOKEN>' \
     -XPOST https://<ldp-cluster>.logs.ovh.com:9200/ldp-logs/_doc \
     -d '{ "test_field" : "OVHcloud", "short_message" : "Hello with IAM" }'

Remarques :

  • Le préfixe d'index/alias est désormais le service name (par exemple ldp-ab-56945) au lieu du nom d'utilisateur. Vous pouvez trouver le service name sur la page d'accueil de Logs Data Platform ou dans l'URN du service (urn:v1:eu:resource:ldp:<service-name>).
  • Le même jeton Bearer peut être utilisé pour interroger le backend OpenSearch :
# Envoyer un log avec IAM (option dédiée dans les versions récentes de curl)
curl -k -v -H 'content-type: application/json' \
     --oauth2-bearer `<YOUR_IAM_TOKEN>` \
     -XGET 'https://gra1.logs.ovh.com:9200/_cluster/health?pretty'

Authentification hybride (jeton Bearer avec schéma Basic)

Pour les clients qui ne prennent pas en charge l'en-tête Authorization: Bearer, vous pouvez utiliser la valeur du jeton Bearer avec un schéma d'authentification Basic en la préfixant par pat_jwt_ comme suit :

Authorization: Basic pat_jwt_<your_value>:<bearer_token_value>

Remplacez <your_value> par n'importe quelle valeur ASCII pour identifier votre Personal Access Token (PAT), et <bearer_token_value> par le jeton obtenu comme décrit ci-dessus. Cela permet à la requête d'être acceptée par l'endpoint OpenSearch avec un couple identifiant/mot de passe, tout en utilisant le même jeton.

Tous les exemples existants utilisant des identifiants classiques restent valides pour les clients qui n'ont pas activé IAM.

Cas d'usage : Vector

Vector est un transmetteur de logs rapide et léger, écrit en Rust. Ce logiciel est assez similaire à Logstash ou Fluent Bit. Il récupère les logs d'une source, les transforme et les envoie dans un format compatible avec le module de sortie configuré.

Les intégrations de Vector sont nombreuses, avec plus de 20 sources, plus de 25 transforms et 30 sinks pris en charge. Il prend en charge OpenSearch comme sink grâce à sa compatibilité Elasticsearch. Nous utiliserons la configuration la plus simple pour le faire fonctionner depuis une source journald vers notre endpoint OpenSearch. N'hésitez pas à consulter la documentation pour explorer toutes les possibilités.

data_dir = "/var/lib/vector" # optional, must be allowed in read-write

[sources.journald]
type = "journald" # required

[transforms.token]
#This VRL transorm add the token
type = "remap"
inputs = ["journald"]
source = '''
."X-OVH-TOKEN" = "`<stream-token>`"
'''

[sinks.ldp]
type = "elasticsearch" # required
inputs = ["token"] # required
mode = "bulk"
api_version = "v7"
compression = "gzip" # optional, default is none
healthcheck = true # required
endpoint = "https://<`<ldp-cluster>`>.logs.ovh.com:9200" # required
bulk.index = "ldp-logs" # required
auth.strategy = "basic"
auth.user = "`<username>`"
auth.password = "`<password>`"

Voici l'explication de cette configuration.

La partie source du fichier de configuration TOML configure la source journald. Par défaut, cette source utilise le répertoire /var/lib/vector pour stocker ses données. Vous pouvez configurer ce répertoire avec l'option globale data_dir.

La partie configuration transform concerne le transform remap. Ce transform, nommé ici token, a pour unique objectif d'ajouter la valeur du jeton du flux. Il récupère les logs depuis l'input nommé journald et ajoute une valeur X-OVH-TOKEN. Cette valeur de jeton se trouve dans le menu ... du flux, sur la page du flux dans le manager Logs Data Platform. Remplacez <stream-token> par la valeur du jeton de votre flux.

La dernière partie est le sink Elasticsearch. Il récupère les données du token issu des inputs précédents et configure plusieurs points :

  • gzip est pris en charge sur notre endpoint, il est donc activé avec la configuration compression.
  • le healthcheck est également pris en charge et vous permet de vous assurer que la plateforme fonctionne correctement
  • la configuration endpoint doit être remplacée par votre cluster attribué
  • le bulk.index doit être défini sur "ldp-logs", notre index spécial de logs OpenSearch
  • le auth.strategy doit être défini sur "basic".
  • auth.user et auth.password doivent être définis avec le nom d'utilisateur du compte Logs Data Platform et son mot de passe associé. Notez que vous pouvez utiliser des jetons à la place de vos identifiants.

Une fois configuré et lancé, vous verrez immédiatement ce type de logs dans Graylog :

vector\_logs

Les logs provenant de journald arrivent entièrement analysés et prêts à être explorés. Utilisez différentes sources et différents transforms pour envoyer les logs de votre application vers Logs Data Platform.

Aller plus loin

Cette page vous a-t-elle aidé ?