Guide de la journalisation

Media CDN enregistre chaque requête HTTP entre le client et la périphérie dans Cloud Logging. Les journaux sont généralement diffusés quasiment en temps réel. Cela inclut la possibilité d'interroger les enregistrements dans Logging et leur exportation vers Cloud Storage et Pub/Sub.

Les entrées de journal contiennent les types d'informations suivants :

  • Informations générales figurant dans la plupart des journaux Google Cloud, telles que la gravité, l'ID de projet, le numéro de projet et l'horodatage.
  • Champs de journal HttpRequest.

  • Métadonnées supplémentaires sur la requête contenues dans structPayload, ce qui inclut :

    • Le numéro ASN du client.
    • Les données de localisation client.
    • L'ID (ville) des caches utilisés pour traiter la réponse.
    • Le nom d'hôte SNI TLS.
    • La version TLS utilisée.

Champs spécifiques au cache

L'objet jsonPayload d'un journal Media CDN contient des métadonnées spécifiques à la manière dont Media CDN diffuse un objet, le statut de mise en cache de l'objet et les états d'erreur rencontrés.

Ces champs, ainsi que des exemples de valeurs, sont présentés dans le tableau suivant.

Champ Exemple de valeur Détails
backendInitialLatency 0.126644940s

La durée nécessaire au backend pour répondre initialement à une requête. Mesurée à partir du moment où le CDN a fini de transmettre la requête vers l'origine par proxy, jusqu'à ce que le CDN commence à recevoir les octets de réponse en provenance de l'origine.

Ce champ n'apparaît dans les journaux que pour le remplissage du cache à partir d'une ressource EdgeCacheOrigin.
backendLatency 0.126666342s

Durée nécessaire au backend pour répondre entièrement à une requête. Mesurée à partir du moment où le CDN a fini de transmettre la requête vers l'origine par proxy, jusqu'à ce que le CDN ait reçu la réponse complète du backend.

Ce champ n'apparaît dans les journaux que pour le remplissage du cache à partir d'une ressource EdgeCacheOrigin.
cacheId MAA-123456 Le code IATA (aéroport) de la ville la plus proche du cache ainsi qu'un identifiant opaque de l'instance de cache. Si plusieurs niveaux de mise en cache sont nécessaires pour répondre à la requête en raison d'un défaut de cache complet ou partiel, la chaîne des emplacements de cache est fournie (par exemple, del-234567, bom-345678, sin-456789), le cache le plus à droite étant le plus proche de l'utilisateur.
cacheKeyFingerprint f63925711b0dd8a9ff861cd303774e6e

Une empreinte opaque de la clé de cache. Les requêtes mappées à la même clé de cache (par exemple, les requêtes pour lesquelles les paramètres de requête ne sont pas inclus ou dans lesquelles l'hôte n'est pas inclus) doivent avoir la même empreinte.

Si le nombre total de requêtes est semblable au nombre total d'empreintes uniques, cela peut indiquer que vos clés de cache sont trop spécifiques.
cacheMode USE_ORIGIN_HEADERS La valeur cdnPolicy.cacheMode est configurée sur la route mise en correspondance avec cette requête.
cacheStatus

Cache hit: hit

Full cache miss: fetch, miss, miss

 L'état du cache au niveau de chaque nœud de cache entre l'utilisateur et le bouclier d'origine, la valeur la plus à droite représentant le cache le plus proche de l'utilisateur.
clientAsn Le numéro ASN (Autonomous System Number), basé sur l'adresse IP du client qui se connecte.
clientCity Mountain View

Le nom de la ville d'origine de la requête (par exemple Mountain View, Californie).

Cet élément peut également être ajouté aux en-têtes de requête et de réponse. Il met en miroir la variable d'en-tête client_city.
clientRegionCode US

Le pays (ou la région) associé à l'adresse IP du client. Il s'agit d'un code de région CLDR au format Unicode (US ou FR, par exemple). Pour la plupart des pays, ces codes correspondent directement aux codes ISO-3166-2.

Cet élément peut également être ajouté aux en-têtes de requête et de réponse. Il met en miroir la variable d'en-tête client_region.
enforcedSecurityPolicy La stratégie de sécurité périphérique de Google Cloud Armor appliquée à la requête du client. Cela inclut des informations supplémentaires sur le nom de la stratégie, sa priorité et l'action appliquée.
httpTtfb 0.157228207s La durée entre le moment où le proxy commence à recevoir des octets de requête et l'envoi du premier octet de réponse (non reçu).
latency 0.157415635s La durée entre le moment où le proxy commence à recevoir des octets de requête et la fin de l'écriture de la réponse au client.
location L'en-tête Location dans la réponse.
metroIataCode MAA Le code IATA (aéroport) de la ville la plus proche du proxy.
origin La ressource EdgeCacheOrigin à partir de laquelle la réponse a été envoyée par proxy.
originalRequestId 19d92668-3948-49d8-9244-25f8252043e4 L'identifiant unique attribué à la requête qui a initialement généré cette réponse. Cet élément est renseigné uniquement si ce paramètre est différent de request_id pour les réponses mises en cache.
originIp L'adresse IP utilisée pour contacter la ressource EdgeCacheOrigin à partir de laquelle la réponse a été envoyée par proxy.
proxyRegionCode US Le pays (ou la région) dans lequel se trouve le proxy. Il s'agit d'un code de région CLDR au format Unicode (US ou FR, par exemple). Pour la plupart des pays, ces codes correspondent directement aux codes ISO-3166-2.
rangeHeader L'en-tête Range dans la requête.
requestId 4bde6381-cd17-47e1-8c2a-1aaa424a1156 L'identifiant unique attribué à la requête par le proxy.
tlsCipherSuite 009C La suite de chiffrement négociée lors du handshake TLS. La valeur se compose de quatre caractères hexadécimaux définis par le Registre de suites de chiffrement TLS de l'IANA. Par exemple, 009C pour TLS_RSA_WITH_AES_128_GCM_SHA256. Cette valeur est vide pour les connexions client non chiffrées.
tlsSniHostname L'indication du nom du serveur (telle que définie dans la RFC 6066), si ce nom est fourni par le client lors du handshake TLS ou QUIC. Le nom d'hôte est converti en minuscules et tous les points se trouvant à la fin du nom sont supprimés.
tlsVersion TLS 1.3 La version de TLS négociée entre le client et le CDN lors du handshake SSL. Les valeurs possibles sont TLS 1, TLS 1.1, TLS 1.2 et TLS 1.3.

Exemple d'entrée de journal

Voici un exemple d'entrée de journal pour une réponse diffusée à partir du cache :

{
  "insertId": "617fa16e-0000-2ac9-9993-d4f547fe67d4@a1",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.cloud.edgecache.v1.EdgeCacheLogEntry",
    "tlsVersion": "TLS 1.3",
    "tlsCipherSuite": "009C", // hex digits for the cipher negotiated
    "cacheId": "maa-132eed13faa13",
    "clientAsn": "9299", // AS the client is associated with
    "origin": "example_origin",
    "clientRegionCode": "IN",
    "metroIataCode": "bom",
    "clientCity": "Mumbai", // City name, in English
    "latency": "0.005105200s",
    "proxyStatus": "Google-Edge-Cache",
    "httpTtfb": "0.005056080s",
    "cacheMode": "FORCE_CACHE_ALL",
    "cacheKeyFingerprint": "c360ac18849b6336",
    "cacheStatus": "hit,stale",
    "enforcedSecurityPolicy": {
      "outcome": "ACCEPT",
      "configuredAction": "ACCEPT",
      "name": "example_policy",
      "priority": 1000
    },
    "originalRequestId": "19d92668-3948-49d8-9244-25f8252043e5",
    "proxyRegionCode": "IN",
    "requestId": "4bde6381-cd17-47e1-8c2a-1aaa424a1156",
    "originIp": "74.125.128.128"
  },
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "https://example.com/image.jpg",
    "requestSize": "3545",
    "status": 200,
    "responseSize": "3716",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36",
    "remoteIp": "62.36.0.43",
    "protocol": "HTTP/2"
  },
  "resource": {
    "type": "edgecache.googleapis.com/EdgeCacheRouteRule",
    "labels": {
      "matched_path": "/",
      "path_matcher_name": "routes",
      "service_name": "example_service",
      "resource_container": "projects/123456789",
      "location": "global",
      "route_destination": "projects/123456789/locations/global/edgeCacheOrigins/example_origin",
      "route_type": "ORIGIN"
    }
  },
  "timestamp": "2022-11-19T00:24:13.695328200Z",
  "logName": "projects/my-project/logs/edgecache.googleapis.com%2Fedge_cache_request",
  "receiveTimestamp": "2022-11-19T00:24:16.715871645Z"
}

Pour réduire le volume de journaux et les frais globaux de Logging, les journaux peuvent éventuellement être échantillonnés ou filtrés si nécessaire. Vous pouvez également acheminer les journaux vers Pub/Sub ou BigQuery pour les analyser dans Google Cloud, ou avec vos outils d'analyse de journaux existants.

Activer les journaux

Logging est désactivé par défaut pour réduire la quantité de données stockée. Les journaux sont acheminés, filtrés et stockés dans Logging.

Pour activer la journalisation pour un service Media CDN spécifique, procédez comme suit :

gcloud edge-cache services update YOUR_SERVICE \
    --enable-logging \
    --logging-sample-rate=1.0

Pour désactiver la journalisation, procédez comme suit :

gcloud edge-cache services update YOUR_SERVICE \
    --no-enable-logging

Pour obtenir l'état actuel de journalisation d'un service, procédez comme suit :

gcloud edge-cache services describe YOUR_SERVICE

Le résultat ressemble à ce qui suit :

...
logConfig:
  enable: true
  sampleRate: 1.0
...

Échantillonner les journaux

Pour de grands volumes de requêtes, il peut être préférable d'échantillonner les journaux plutôt que de journaliser chaque requête et de vous appuyer sur des métriques de surveillance et d'enquête proactives.

Pour n'ingérer et stocker les journaux que pour 10 % de vos requêtes, vous pouvez définir logConfig.sampleRate sur 0.1.

gcloud edge-cache services update YOUR_SERVICE \
    --enable-logging \
    --logging-sample-rate=0.1

Logging doit être activé pour modifier le taux d'échantillonnage.

Sauf indication contraire, le taux d'échantillonnage par défaut est de 1.0 (100 %), ce qui signifie que chaque requête pour le service configuré est journalisée.

Journaux de requête

Pour interroger des journaux, vous pouvez utiliser l'explorateur de journaux dans la console Google Cloud ou Google Cloud CLI.

Pour afficher les journaux dans la console Google Cloud, filtrez le type de ressource sur Media CDN et (éventuellement) sur un nom de projet ou de service.

La requête de journalisation suivante affiche les journaux de tous vos services Media CDN :

resource.type="edgecache.googleapis.com/EdgeCacheRouteRule"

Pour filtrer les journaux associés à une ressource EdgeCacheService et à un projet spécifiques, vous pouvez étendre cette requête :

resource.type="edgecache.googleapis.com/EdgeCacheRouteRule"
resource.labels.resource_container="projects/12345678"
resource.labels.service_name="MY_PROJECT"

Pour rechercher des noms partiels ou utiliser des expressions régulières, consultez la documentation sur la syntaxe de journalisation.

Exemple : Identifier les défauts de cache (miss)

Une requête pour un objet peut résulter en un défaut de cache (miss) et entraîner un remplissage de cache pour diverses raisons :

  • Valeur TTL trop courte.
  • Clé de cache trop spécifique.
  • Trop peu de requêtes pour justifier la mise en cache.

Pour identifier les défauts de cache, vous pouvez filtrer les journaux dans l'explorateur de journaux.

La requête de journalisation suivante affiche les requêtes pouvant être mises en cache (recherchées), mais qui nécessitent un remplissage à partir de l'origine :

resource.type="edgecache.googleapis.com/EdgeCacheRouteRule"
resource.labels.resource_container="projects/12345678"
resource.labels.service_name="MY_PROJECT"
jsonPayload.cacheStatus="miss"

Si vous devez filtrer par URL spécifique, vous pouvez filtrer sur le champ httpRequest.requestUrl :

httpRequest.requestUrl = "URL"

Pour filtrer sur une partie de l'URL, telle que le composant de chemin d'accès, utilisez l'opérateur has :

# `:` is the `has` comparison operator
httpRequest.requestUrl: "/videos/1381381_1080.mp4"
# You can use `OR` or `AND` to filter on multiple values
httpRequest.requestUrl: ("https://media-test.example.com/" OR "https://canary.example.net")

Pour en savoir plus sur la syntaxe complète de Logging pour la mise en correspondance et le filtrage, consultez la documentation sur les requêtes de journaux avancées.

Règles de conservation

Logging accepte la définition de règles de conservation personnalisées, y compris les règles individuelles par récepteur.

Filtrer les journaux stockés

Pour filtrer les journaux avant de les stocker (par exemple, pour ne capturer que des champs pertinents afin de réduire le volume total de journaux à stocker et à interroger), vous pouvez configurer des règles d'exclusion de journaux, qui vous permettent de définir une requête (filtre) qui inclut ou exclut des champs avant le stockage.

Vous pouvez également configurer plusieurs filtres, par exemple pour capturer tous les défauts de cache ou toutes les requêtes portant sur un nom d'hôte spécifique, et ne prélever qu'un échantillon de tous les journaux.

Exporter des journaux

Vous pouvez exporter les journaux à partir de Logging en consultant la présentation des exportations de journaux, qui couvre les points suivants :

  • Comment exporter des journaux vers Cloud Storage ou BigQuery.
  • Exporter vers Pub/Sub et consommer les journaux en utilisant des fonctions Cloud Functions ou des services externes.
  • Agrégation de journaux sur plusieurs projets.

Media CDN s'intègre directement à Logging.

Étapes suivantes