Configurazione dell'agente operativo

La personalizzazione della configurazione di Ops Agent ti consente di controllare il modo in cui l'agente raccoglie, analizza e instrada log, metriche e tracce dalle tue istanze Compute Engine. Sebbene Ops Agent includa una configurazione predefinita integrata per i log di sistema e le metriche host comuni, puoi definire override personalizzati per adattare la raccolta di dati di telemetria ai tuoi workload.

Attività di configurazione comuni

Puoi modificare la configurazione di Ops Agent per raggiungere i seguenti obiettivi:

Modello di configurazione

Ops Agent utilizza una configurazione predefinita integrata che non puoi modificare direttamente. Devi invece creare un file di override che viene unito alla configurazione integrata al riavvio dell'agente.

I componenti di base della configurazione sono i seguenti:

  • receivers: questo elemento descrive ciò che viene raccolto dall'agente.
  • processors: questo elemento descrive in che modo l'agente può modificare le informazioni raccolte.
  • service: questo elemento collega i receiver e i processori per creare flussi di dati, chiamati pipeline. L'elemento service contiene un elemento pipelines, che può contenere più pipeline.

La configurazione integrata è costituita da questi elementi, che utilizzi per eseguire l'override della configurazione integrata.

Configurazione integrata

La configurazione integrata di Ops Agent definisce la raccolta predefinita di log e metriche. Di seguito è riportata la configurazione integrata per Linux e Windows:

Linux

Per impostazione predefinita, Ops Agent raccoglie log syslog basati su file e metriche host.

Per saperne di più sulle metriche raccolte, consulta Metriche importate dai receiver.

logging:
  receivers:
    syslog:
      type: files
      include_paths:
      - /var/log/messages
      - /var/log/syslog
  service:
    pipelines:
      default_pipeline:
        receivers: [syslog]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics]
        processors: [metrics_filter]

Windows

Per impostazione predefinita, Ops Agent raccoglie i log eventi di Windows dai canali System, Application e Security, nonché le metriche dell'host, di IIS e di SQL Server.

Per saperne di più sulle metriche raccolte, consulta Metriche importate dai receiver.

logging:
  receivers:
    windows_event_log:
      type: windows_event_log
      channels: [System, Application, Security]
  service:
    pipelines:
      default_pipeline:
        receivers: [windows_event_log]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
    iis:
      type: iis
      collection_interval: 60s
    mssql:
      type: mssql
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics, iis, mssql]
        processors: [metrics_filter]

Queste configurazioni sono descritte in maggiore dettaglio in Configurazione di Logging e Configurazione delle metriche.

Configurazione specificata dall'utente

Per eseguire l'override della configurazione integrata, devi aggiungere nuovi elementi di configurazione al file di configurazione utente. Inserisci la configurazione per Ops Agent nei seguenti file:

  • Per Linux: /etc/google-cloud-ops-agent/config.yaml
  • Per Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

Qualsiasi configurazione specificata dall'utente viene unita alla configurazione integrata quando l'agente viene riavviato.

Per eseguire l'override di un receiver, un processore o una pipeline integrati, ridefiniscili nel file config.yaml dichiarandoli con lo stesso identificatore. A partire dalla versione 2.31.0 di Ops Agent, puoi anche configurare la funzionalità di rotazione dei log dell'agente. Per saperne di più, consulta Configura la rotazione dei log in Ops Agent.

Ad esempio, la configurazione integrata per le metriche include un ricevitore hostmetrics che specifica un intervallo di raccolta di 60 secondi. Per modificare l'intervallo di raccolta per le metriche host in 30 secondi, includi un ricevitore di metriche denominato hostmetrics nel file config.yaml che imposta il valore collection_interval su 30 secondi, come mostrato nell'esempio seguente:

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 30s

Per altri esempi di modifica delle configurazioni integrate, consulta Configurazione del logging e Configurazione delle metriche. Puoi anche disattivare la raccolta dei dati di logging o delle metriche. Queste modifiche sono descritte nelle configurazioni di logging service di esempio e nelle configurazioni delle metriche service.

Puoi utilizzare questo file per impedire all'agente di raccogliere i log personali e di inviarli a Cloud Logging. Per saperne di più, consulta Raccolta di log interni.

Utilizza questo file anche per configurare la funzionalità di rotazione dei log dell'agente. Per saperne di più, consulta Configura la rotazione dei log in Ops Agent.

Non puoi configurare Ops Agent per esportare log o metriche in servizi diversi da Cloud Logging e Cloud Monitoring.

Configurazioni di logging

La configurazione logging utilizza il modello di configurazione descritto in precedenza:

  • receivers: questo elemento descrive i dati da raccogliere dai file di log; questi dati vengono mappati in un modello <timestamp, record>.
  • processors: questo elemento facoltativo descrive in che modo l'agente può modificare le informazioni raccolte.
  • service: questo elemento collega i receiver e i processori per creare flussi di dati, chiamati pipeline. L'elemento service contiene un elemento pipelines, che può includere più definizioni di pipeline.

Ogni ricevitore e ogni processore possono essere utilizzati in più pipeline.

Le sezioni seguenti descrivono ciascuno di questi elementi.

Ops Agent invia i log a Cloud Logging. Non puoi configurarlo per esportare i log in altri servizi. Tuttavia, puoi configurare Cloud Logging per esportare i log. Per saperne di più, consulta Instrada i log alle destinazioni supportate.

Ricevitori di Logging

L'elemento receivers contiene un insieme di destinatari, ciascuno identificato da un RECEIVER_ID. Un ricevitore descrive come recuperare i log, ad esempio tramite il tailing dei file, utilizzando una porta TCP o dal log eventi di Windows.

Struttura dei ricevitori di logging

Ogni ricevitore deve avere un identificatore, RECEIVER_ID, e includere un elemento type. I tipi validi sono:

  • files: raccoglie i log seguendo i file su disco.
  • fluent_forward (Ops Agent versione 2.12.0 e successive): raccoglie i log inviati tramite il protocollo Fluent Forward su TCP.
  • tcp (Ops Agent versione 2.3.0 e successive): raccoglie i log in formato JSON ascoltando una porta TCP.
  • Solo per Linux:
    • syslog: raccoglie i messaggi Syslog tramite TCP o UDP.
    • systemd_journald (Ops Agent 2.4.0 e versioni successive): raccoglie i log del journal systemd dal servizio systemd-journald.
  • Solo Windows:
    • windows_event_log: raccoglie i log eventi di Windows utilizzando l'API Log eventi di Windows.
  • Ricevitori di log di applicazioni di terze parti

La struttura receivers è simile alla seguente:

receivers:
  RECEIVER_ID:
    type: files
    ...
  RECEIVER_ID_2:
    type: syslog
    ...

A seconda del valore dell'elemento type, potrebbero essere disponibili altre opzioni di configurazione, come segue:

  • files ricevitori:

    • include_paths: obbligatorio. Un elenco di percorsi del file system da leggere seguendo ogni file. Nei percorsi è possibile utilizzare i seguenti caratteri jolly:

      • *: corrisponde a qualsiasi sequenza di caratteri non separatori di percorso all'interno di un singolo nome di directory o file.

        • Esempio (Linux): /var/log/*.log corrisponde a tutti i file che terminano con .log direttamente all'interno di /var/log/.
        • Esempio (Linux): /var/log/app_*/server.log corrisponde a /var/log/app_1/server.log e /var/log/app_2/server.log, ma non corrisponde a /var/log/app_1/v2/server.log.

      • ** (globstar): corrisponde a zero o più directory in un percorso. Questo pattern viene utilizzato per trovare i file in più livelli di directory (in modo ricorsivo).

        • Esempio (Linux): /var/log/**/*.log corrisponde a qualsiasi file che termina con .log all'interno di /var/log o di una delle sue sottodirectory a qualsiasi profondità (ad es. /var/log/app1.log, /var/log/apache2/access.log).
        • Esempio (Linux): per raccogliere i log dalle istanze dell'applicazione che creano sottodirectory con controllo delle versioni o specifiche per l'istanza, come /opt/my-app/logs/instance-01/app.log, /opt/my-app/logs/groupA/instance-02/app.log, è possibile utilizzare globstar: /opt/my-app/logs/**/*.log

      Per un elenco dei file di log delle applicazioni Linux più comuni, consulta File di log Linux comuni.

    • exclude_paths: (Facoltativo) Un elenco di pattern di percorsi del file system da escludere dall'insieme corrispondente a include_paths.

    • record_log_file_path: (Facoltativo) Se impostato su true, il percorso del file specifico da cui è stato ottenuto il record di log viene visualizzato nella voce di log di output come valore dell'etichetta agent.googleapis.com/log_file_path. Quando utilizzi un carattere jolly, viene registrato solo il percorso del file da cui è stato ottenuto il record.

    • wildcard_refresh_interval: (Facoltativo) L'intervallo di aggiornamento dei percorsi dei file con caratteri jolly in include_paths. Fornito come durata, ad esempio 30s, 2m. Questa proprietà potrebbe essere utile in caso di throughput di logging elevati, in cui i file di log vengono ruotati più velocemente rispetto all'intervallo predefinito. Se non viene specificato, l'intervallo predefinito è di 60 secondi.

  • fluent_forward ricevitori:

    • listen_host: (Facoltativo) Un indirizzo IP su cui rimanere in ascolto. Il valore predefinito è 127.0.0.1.

    • listen_port: (Facoltativo) Una porta su cui rimanere in ascolto. Il valore predefinito è 24224.

  • Ricevitori syslog (solo per Linux):

    • transport_protocol: valori supportati: tcp, udp.

    • listen_host: un indirizzo IP su cui ascoltare.

    • listen_port: una porta su cui ascoltare.

  • tcp ricevitori:

    • format: obbligatorio. Formato log. Valore supportato: json.

    • listen_host: (Facoltativo) Un indirizzo IP su cui rimanere in ascolto. Il valore predefinito è 127.0.0.1.

    • listen_port: (Facoltativo) Una porta su cui rimanere in ascolto. Il valore predefinito è 5170.

  • Ricevitori windows_event_log (solo per Windows):

    • channels: obbligatorio. Un elenco di canali del log eventi di Windows da cui leggere i log.

    • receiver_version: (Facoltativo) Controlla quale API del log eventi di Windows utilizzare. I valori supportati sono 1 e 2. Il valore predefinito è 1.

    • render_as_xml: (Facoltativo) Se impostato su true, tutti i campi del log eventi, ad eccezione di jsonPayload.Message e jsonPayload.StringInserts, vengono visualizzati come documento XML in un campo stringa denominato jsonPayload.raw_xml. Il valore predefinito è false. Questo valore non può essere impostato su true quando receiver_version è 1.

Esempi di ricevitore di logging

Ricevitore files di esempio:

receivers:
  RECEIVER_ID:
    type: files

    include_paths: [/var/log/*.log]
    exclude_paths: [/var/log/not-this-one.log]
    record_log_file_path: true

Ricevitore fluent_forward di esempio:

receivers:
  RECEIVER_ID:
    type: fluent_forward

    listen_host: 127.0.0.1
    listen_port: 24224

Ricevitore syslog di esempio (solo Linux):

receivers:
  RECEIVER_ID:
    type: syslog

    transport_protocol: tcp
    listen_host: 0.0.0.0
    listen_port: 5140

Ricevitore tcp di esempio:

receivers:
  RECEIVER_ID:
    type: tcp

    format: json
    listen_host: 127.0.0.1
    listen_port: 5170

Ricevitore windows_event_log di esempio (solo Windows):

receivers:
  RECEIVER_ID:
    type: windows_event_log

    channels: [System,Application,Security]

Ricevitore windows_event_log di esempio che esegue l'override del ricevitore integrato per utilizzare la versione 2:

receivers:
  windows_event_log:
    type: windows_event_log

    channels: [System,Application,Security]
    receiver_version: 2

Ricevitore systemd_journald di esempio:

receivers:
  RECEIVER_ID:
    type: systemd_journald

Campi speciali nei payload strutturati

Per i processori e i receiver che possono importare dati strutturati (i receiver fluent_forward e tcp e il processore parse_json), puoi impostare campi speciali nell'input che verranno mappati a campi specifici nell'oggetto LogEntry che l'agente scrive nell'API Logging.

Quando Ops Agent riceve dati di log strutturati esterni, inserisce i campi di primo livello nel campo jsonPayload di LogEntry, a meno che il nome del campo non sia elencato nella tabella seguente:

Campo record Campo LogEntry

Opzione 1


"timestamp": {
  "seconds": CURRENT_SECONDS,
  "nanos": CURRENT_NANOS,
}

Opzione 2


{
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS,
}
 		timestamp
receiver_id (non è un campo del record) logName
logging.googleapis.com/httpRequest (HttpRequest) httpRequest
logging.googleapis.com/severity (string) severity
logging.googleapis.com/labels (struct of string:string) labels
logging.googleapis.com/operation (struct) operation
logging.googleapis.com/sourceLocation (struct) sourceLocation
logging.googleapis.com/trace (string) trace
logging.googleapis.com/spanId (string) spanId

Tutti i campi dei record strutturati rimanenti rimangono parte della struttura jsonPayload.

File di log di Linux comuni

La tabella seguente elenca i file di log comuni per le applicazioni Linux utilizzate di frequente:

Applicazione File di log comuni
apache Per informazioni sui file di log di Apache, consulta Monitoraggio di applicazioni di terze parti: server web Apache.
cassandra Per informazioni sui file di log di Cassandra, consulta Monitoraggio delle applicazioni di terze parti: Cassandra.
chef /var/log/chef-server/bookshelf/current
/var/log/chef-server/chef-expander/current
/var/log/chef-server/chef-pedant/http-traffic.log
/var/log/chef-server/chef-server-webui/current
/var/log/chef-server/chef-solr/current
/var/log/chef-server/erchef/current
/var/log/chef-server/erchef/erchef.log.1
/var/log/chef-server/nginx/access.log
/var/log/chef-server/nginx/error.log
/var/log/chef-server/nginx/rewrite-port-80.log
/var/log/chef-server/postgresql/current
gitlab /home/git/gitlab/log/application.log
/home/git/gitlab/log/githost.log
/home/git/gitlab/log/production.log
/home/git/gitlab/log/satellites.log
/home/git/gitlab/log/sidekiq.log
/home/git/gitlab/log/unicorn.stderr.log
/home/git/gitlab/log/unicorn.stdout.log
/home/git/gitlab-shell/gitlab-shell.log
jenkins /var/log/jenkins/jenkins.log
jetty /var/log/jetty/out.log
/var/log/jetty/*.request.log
/var/log/jetty/*.stderrout.log
joomla /var/www/joomla/logs/*.log
magento /var/www/magento/var/log/exception.log
/var/www/magento/var/log/system.log
/var/www/magento/var/report/*
mediawiki /var/log/mediawiki/*.log
memcached Per informazioni sui file di log di Memcached, consulta Monitoraggio di applicazioni di terze parti: Memcached.
mongodb Per informazioni sui file di log di MongoDB, consulta Monitoraggio delle applicazioni di terze parti: MongoDB.
mysql Per informazioni sui file di log di MySQL, consulta Monitoraggio delle applicazioni di terze parti: MySQL.
nginx Per informazioni sui file di log di nginx, consulta Monitoraggio delle applicazioni di terze parti: nginx.
postgres Per informazioni sui file di log di PostgreSQL, consulta Monitoraggio di applicazioni di terze parti: PostgreSQL.
puppet /var/log/puppet/http.log
/var/log/puppet/masterhttp.log
puppet-enterprise /var/log/pe-activemq/activemq.log
/var/log/pe-activemq/wrapper.log
/var/log/pe-console-auth/auth.log
/var/log/pe-console-auth/cas_client.log
/var/log/pe-console-auth/cas.log
/var/log/pe-httpd/access.log
/var/log/pe-httpd/error.log
/var/log/pe-httpd/other_vhosts_access.log
/var/log/pe-httpd/puppetdashboard.access.log
/var/log/pe-httpd/puppetdashboard.error.log
/var/log/pe-httpd/puppetmasteraccess.log
/var/log/pe-mcollective/mcollective_audit.log
/var/log/pe-mcollective/mcollective.log
/var/log/pe-puppet-dashboard/certificate_manager.log
/var/log/pe-puppet-dashboard/event-inspector.log
/var/log/pe-puppet-dashboard/failed_reports.log
/var/log/pe-puppet-dashboard/live-management.log
/var/log/pe-puppet-dashboard/mcollective_client.log
/var/log/pe-puppet-dashboard/production.log
/var/log/pe-puppetdb/pe-puppetdb.log
/var/log/pe-puppet/masterhttp.log
/var/log/pe-puppet/rails.log
rabbitmq Per informazioni sui file di log di RabbitMQ, consulta Monitoraggio di applicazioni di terze parti: RabbitMQ.
redis Per informazioni sui file di log di Redis, consulta Monitoraggio delle applicazioni di terze parti: Redis.
redmine /var/log/redmine/*.log
sale /var/log/salt/key
/var/log/salt/master
/var/log/salt/minion
/var/log/salt/syndic.loc
solr Per informazioni sui file di log di Apache Solr, consulta Monitoraggio delle applicazioni di terze parti: Apache Solr.
sugarcrm /var/www/*/sugarcrm.log
syslog /var/log/syslog
/var/log/messages
tomcat Per informazioni sui file di log di Apache Tomcat, consulta Monitoraggio delle applicazioni di terze parti: Apache Tomcat.
zookeeper Per informazioni sui file di log di Apache ZooKeeper, consulta Monitoraggio di applicazioni di terze parti: Apache ZooKeeper.

Etichette importate predefinite

Per impostazione predefinita, i log possono contenere le seguenti etichette in LogEntry:

Campo Valore di esempio Descrizione
labels."compute.googleapis.com/resource_name" test_vm Il nome della macchina virtuale da cui proviene questo log. Scritto per tutti i log.
labels."logging.googleapis.com/instrumentation_source" agent.googleapis.com/apache_access Il valore del ricevitore type da cui proviene questo log, preceduto da agent.googleapis.com/. Scritto solo dai destinatari delle integrazioni di terze parti.

Processori di logging

L'elemento facoltativo processors contiene un insieme di istruzioni di elaborazione, ciascuna identificata da un PROCESSOR_ID. Un processore descrive come manipolare le informazioni raccolte da un ricevitore.

Ogni processore deve avere un identificatore univoco e includere un elemento type. I tipi validi sono:

  • parse_json: analizza i log strutturati in formato JSON.
  • parse_multiline: analizza i log su più righe. (solo Linux)
  • parse_regex: analizza i log formattati come testo tramite pattern regex per trasformarli in log strutturati in formato JSON.
  • exclude_logs: esclude i log che corrispondono alle regole specificate (a partire dalla versione 2.9.0).
  • modify_fields: imposta/trasforma i campi nelle voci di log (a partire dalla versione 2.14.0).

La struttura processors è simile alla seguente:

processors:
  PROCESSOR_ID:
    type: parse_json
    ...
  PROCESSOR_ID_2:
    type: parse_regex
    ...

A seconda del valore dell'elemento type, sono disponibili altre opzioni di configurazione, come segue.

Processore parse_json

Struttura della configurazione

processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    <field name within jsonPayload>
    time_format: <strptime format string>

Il processore parse_json analizza il JSON di input nel campo jsonPayload di LogEntry. Altre parti di LogEntry possono essere analizzate impostando determinati campi speciali di primo livello.

  • time_key: (Facoltativo) Se la voce di log fornisce un campo con un timestamp, questa opzione specifica il nome del campo. Il valore estratto viene utilizzato per impostare il campo timestamp del LogEntry risultante e viene rimosso dal payload.

    Se specifichi l'opzione time_key, devi anche specificare quanto segue:

    • time_format: obbligatorio se viene utilizzato time_key. Questa opzione specifica il formato del campo time_key in modo che possa essere riconosciuto e analizzato correttamente. Per i dettagli del formato, consulta la guida di strptime(3).
Configurazione di esempio
processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

Processore parse_multiline

Struttura della configurazione

processors:
  PROCESSOR_ID:
    type: parse_multiline

    match_any:
    - type: <type of the exceptions>
      language: <language name>

  • match_any: obbligatorio. Un elenco di una o più regole.

    • type: obbligatorio. È supportato un solo valore:

      • language_exceptions: consente al processore di concatenare le eccezioni in un'unica LogEntry, in base al valore dell'opzione language.

    • language: obbligatorio. È supportato un solo valore:

      • java: concatena le eccezioni Java comuni in un'unica LogEntry.
      • python: concatena le eccezioni Python comuni in un'unica LogEntry.
      • go: concatena le eccezioni Go comuni in un'unica LogEntry.
Configurazione di esempio
logging:
  receivers:
    custom_file1:
      type: files
      include_paths:
      - /tmp/test-multiline28
  processors:
    parse_java_multiline:
      type: parse_multiline
      match_any:
      - type: language_exceptions
        language: java
    extract_structure:
      type: parse_regex
      field: message
      regex: "^(?<time>[\d-]*T[\d:.Z]*) (?<severity>[^ ]*) (?<file>[^ :]*):(?<line>[\d]*) - (?<message>(.|\\n)*)$"
      time_key: time
      time_format: "%Y-%m-%dT%H:%M:%S.%L"
    move_severity:
      type: modify_fields
      fields:
        severity:
          move_from: jsonPayload.severity
  service:
    pipelines:
      pipeline1:
        receivers: [custom_file1]
        processors: [parse_java_multiline, extract_structure, move_severity]

Nel processore extract_structure, l'istruzione field: message indica che l'espressione regolare viene applicata al campo jsonPayload.message della voce di log. Per impostazione predefinita, il ricevitore dei file inserisce ogni riga del file di log in una voce di log con un singolo campo di payload denominato jsonPayload.message.

Il processore extract_structure inserisce i campi estratti nei sottocampi del campo LogEntry.jsonPayload. Altre istruzioni nel file YAML causano lo spostamento di due dei campi estratti, time e severity. L'istruzione time_key: time estrae il campo LogEntry.jsonPayload.time, analizza il timestamp e poi aggiunge il campo LogEntry.timestamp. Il processore move_severity sposta il campo della gravità dal campo LogEntry.jsonPayload.severity al campo LogEntry.severity.

File di log di esempio:

2022-10-17T22:00:00.187512963Z ERROR HelloWorld:16 - javax.servlet.ServletException: Something bad happened
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)
Caused by: com.example.myproject.MyProjectServletException
    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)
    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)
    ... 27 common frames omitted

L'agente importa ogni riga del file di log in Cloud Logging nel seguente formato:

{
  "insertId": "...",
  "jsonPayload": {
    "line": "16",
    "message": "javax.servlet.ServletException: Something bad happened\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)\nCaused by: com.example.myproject.MyProjectServletException\n    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)\n    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)\n    ... 27 common frames omitted\n",
    "file": "HelloWorld"
  },
  "resource": {
    "type": "gce_instance",
    "labels": {
      "instance_id": "...",
      "project_id": "...",
      "zone": "..."
    }
  },
  "timestamp": "2022-10-17T22:00:00.187512963Z",
  "severity": "ERROR",
  "labels": {
    "compute.googleapis.com/resource_name": "..."
  },
  "logName": "projects/.../logs/custom_file",
  "receiveTimestamp": "2022-10-18T03:12:38.430364391Z"
}

Processore parse_regex

Struttura della configurazione

processors:
  PROCESSOR_ID:
    type: parse_regex

    regex: <regular expression>

    time_key:    <field name within jsonPayload>
    time_format: <format string>

  • time_key: (Facoltativo) Se la voce di log fornisce un campo con un timestamp, questa opzione specifica il nome del campo. Il valore estratto viene utilizzato per impostare il campo timestamp del LogEntry risultante e viene rimosso dal payload.

    Se specifichi l'opzione time_key, devi anche specificare quanto segue:

    • time_format: obbligatorio se viene utilizzato time_key. Questa opzione specifica il formato del campo time_key in modo che possa essere riconosciuto e analizzato correttamente. Per i dettagli del formato, consulta la guida di strptime(3).

  • regex: obbligatorio. L'espressione regolare per l'analisi del campo. L'espressione deve includere i nomi delle chiavi per le sottoespressioni corrispondenti, ad esempio "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$".

    Il testo corrispondente ai gruppi Capture denominati verrà inserito nei campi del campo jsonPayload di LogEntry. Per aggiungere ulteriore struttura ai log, utilizza il processore modify_fields.

    Per un insieme di espressioni regolari per estrarre informazioni dai file di log delle applicazioni Linux comuni, consulta File di log Linux comuni.

Configurazione di esempio
processors:
  PROCESSOR_ID:
    type: parse_regex

    regex:       "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$"
    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

Processore exclude_logs

Struttura della configurazione:

type: exclude_logs
match_any:
  - <filter>
  - <filter>

La configurazione di primo livello per questo processore contiene un singolo campo, match_any, che contiene un elenco di regole di filtro.

  • match_any: obbligatorio. Un elenco di una o più regole. Se una voce di log corrisponde a una regola, Ops Agent non la importa.

    I log importati da Ops Agent seguono la struttura LogEntry. I nomi dei campi sono sensibili alle maiuscole. Puoi specificare regole solo in base ai seguenti campi e ai relativi sottocampi:

    • httpRequest
    • jsonPayload
    • labels
    • operation
    • severity
    • sourceLocation
    • trace
    • spanId

    La seguente regola di esempio

    severity =~ "(DEBUG|INFO)"

    utilizza un'espressione regolare per escludere tutti i log di livello DEBUG e INFO.

    Le regole seguono la sintassi del linguaggio di query di Cloud Logging, ma supportano solo un sottoinsieme delle funzionalità supportate dal linguaggio di query di Logging:

    • Operatori di confronto: =, !=, :, =~, !~. Sono supportati solo i confronti di stringhe.
    • Operatore di navigazione: .. Ad esempio jsonPayload.message.
    • Operatori booleani: AND, OR, NOT.
    • Raggruppamento di espressioni con ( ).

Configurazione di esempio

processors:
  PROCESSOR_ID:
    type: exclude_logs
    match_any:
    - '(jsonPayload.message =~ "log spam 1" OR jsonPayload.message =~ "log spam 2") AND severity = "ERROR"'
    - 'jsonPayload.application = "foo" AND severity = "INFO"'

modify_fields Processore

Il processore modify_fields consente di personalizzare la struttura e i contenuti delle voci di log.

Struttura della configurazione

type: modify_fields
fields:
  <destination field>:
    # Source
    move_from: <source field>
    copy_from: <source field>
    static_value: <string>
    
    # Mutation
    default_value: <string>
    map_values:
      <old value>: <new value>
    type: {integer|float}
    omit_if: <filter>

La configurazione di primo livello per questo processore contiene un singolo campo, fields, che contiene una mappa dei nomi dei campi di output e delle traduzioni corrispondenti. Per ogni campo di output, vengono applicate un'origine facoltativa e zero o più operazioni di mutazione.

Tutti i nomi dei campi utilizzano la sintassi separata da punti del linguaggio di query di Cloud Logging. I filtri utilizzano il linguaggio di query di Cloud Logging.

Tutte le trasformazioni vengono applicate in parallelo, il che significa che le origini e i filtri operano sulla voce di log di input originale e pertanto non possono fare riferimento al nuovo valore di altri campi modificati dallo stesso processore.

Opzioni di origine: è consentita al massimo un'origine specificata.

  • Nessuna origine specificata

    Se non viene specificato alcun valore di origine, il valore esistente nel campo di destinazione verrà modificato.

  • move_from: <source field>

    Il valore di <source field> verrà utilizzato come origine per il campo di destinazione. Inoltre, <source field> verrà rimosso dalla voce di log. Se un campo di origine è referenziato sia da move_from sia da copy_from, il campo di origine verrà comunque rimosso.

  • copy_from: <source field>

    Il valore di <source field> verrà utilizzato come origine per il campo di destinazione. <source field> non verrà rimosso dalla voce di log, a meno che non venga fatto riferimento anche da un'operazione move_from o non venga modificato in altro modo.

  • static_value: <string>

    La stringa statica <string> verrà utilizzata come origine per il campo di destinazione.

Opzioni di mutazione: a un singolo campo possono essere applicati zero o più operatori di mutazione. Se vengono forniti più operatori, verranno sempre applicati nel seguente ordine.

  1. default_value: <string>

    Se il campo di origine non esisteva, il valore di output verrà impostato su <string>. Se il campo di origine esiste già (anche se contiene una stringa vuota), il valore originale non viene modificato.

  2. map_values: <map>

    Se il valore di input corrisponde a una delle chiavi in <map>, il valore di output verrà sostituito con il valore corrispondente della mappa.

  3. map_values_exclusive: {true|false}

    Se il valore <source field> non corrisponde ad alcuna chiave specificata nelle coppie map_values, il campo di destinazione verrà forzatamente annullato se map_values_exclusive è true o lasciato invariato se map_values_exclusive è false.

  4. type: {integer|float}

    Il valore di input verrà convertito in un numero intero o in un numero in virgola mobile. Se la stringa non può essere convertita in un numero, il valore di output non verrà impostato. Se la stringa contiene un numero in virgola mobile, ma il tipo è specificato come integer, il numero verrà troncato a un numero intero.

    Tieni presente che l'API Cloud Logging utilizza JSON e pertanto non supporta un intero a 64 bit completo; se è necessario un intero a 64 bit (o superiore), deve essere archiviato come stringa nella voce di log.

  5. omit_if: <filter>

    Se il filtro corrisponde al record di log di input, il campo di output non verrà impostato. Può essere utilizzato per rimuovere valori segnaposto, ad esempio:

    httpRequest.referer:
  move_from: jsonPayload.referer
  omit_if: httpRequest.referer = "-"

Configurazioni di esempio

Il processore parse_json trasforma un file JSON contenente

{
  "http_status": "400",
  "path": "/index.html",
  "referer": "-"
}

in una struttura LogEntry simile alla seguente:

{
  "jsonPayload": {
    "http_status": "400",
    "path": "/index.html",
    "referer": "-"
  }
}

Questo potrebbe poi essere trasformato con modify_fields in questo LogEntry:

{
  "httpRequest": {
    "status": 400,
    "requestUrl": "/index.html",
  }
}

utilizzando questa configurazione di Ops Agent:

logging:
  receivers:
    in:
      type: files
      include_paths:
      - /var/log/http.json
  processors:
    parse_json:
      type: parse_json
    set_http_request:
      type: modify_fields
      fields:
        httpRequest.status:
          move_from: jsonPayload.http_status
          type: integer
        httpRequest.requestUrl:
          move_from: jsonPayload.path
        httpRequest.referer:
          move_from: jsonPayload.referer
          omit_if: jsonPayload.referer = "-"
  service:
    pipelines:
      pipeline:
        receivers: [in]
        processors: [parse_json, set_http_request]

Questa configurazione legge i log in formato JSON da /var/log/http.json e compila parte della struttura httpRequest dai campi dei log.

Servizio di logging

Il servizio di logging personalizza il livello di dettaglio dei log di Ops Agent e collega i ricevitori e i processori di logging in pipeline. La sezione service contiene i seguenti elementi:

  • log_level
  • pipelines

Livello di dettaglio dei log

Il campo log_level, disponibile con Ops Agent versione 2.6.0 e successive, personalizza il livello di dettaglio dei log del sottomodulo di logging di Ops Agent. Il valore predefinito è info. Le opzioni disponibili sono: error, warn, info, debug, trace.

La seguente configurazione personalizza il livello di dettaglio dei log per il sottomodulo di logging in modo che sia debug:

logging:
  service:
    log_level: debug

Pipeline di logging

Il campo pipelines può contenere più ID e definizioni di pipeline. Ogni valore pipeline è costituito dai seguenti elementi:

  • receivers: obbligatorio per le nuove pipeline. Un elenco di ID ricevitore, come descritto in Ricevitori di logging. L'ordine degli ID destinatario nell'elenco non è rilevante. La pipeline raccoglie i dati da tutti i receiver elencati.

  • processors: (Facoltativo) Un elenco di ID processore, come descritto in Processori di logging. L'ordine degli ID di processo nell'elenco è importante. Ogni record viene eseguito dai processori nell'ordine elencato.

Esempi di configurazioni di logging di service

Una configurazione service ha la seguente struttura:

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

Per impedire all'agente di raccogliere e inviare voci /var/log/message o /var/log/syslog, ridefinisci la pipeline predefinita con un elenco receivers vuoto e nessun processore. Questa configurazione non arresta il sottocomponente di logging dell'agente, perché l'agente deve essere in grado di raccogliere i log per il sottocomponente di monitoraggio. L'intera configurazione di logging vuota è simile alla seguente:

logging:
  service:
    pipelines:
      default_pipeline:
        receivers: []

La seguente configurazione service definisce una pipeline con l'ID custom_pipeline:

logging:
  service:
    pipelines:
      custom_pipeline:
        receivers:
        - RECEIVER_ID
        processors:
        - PROCESSOR_ID

Configurazioni delle metriche

La configurazione metrics utilizza il modello di configurazione descritto in precedenza:

  • receivers: un elenco di definizioni dei receiver. Un receiver descrive l'origine delle metriche, ad esempio metriche di sistema come cpu o memory. I receiver in questo elenco possono essere condivisi tra più pipeline.
  • processors: un elenco di definizioni del processore. Un processor descrive come modificare le metriche raccolte da un ricevitore.
  • service: contiene una sezione pipelines che è un elenco di definizioni pipeline. Un pipeline collega un elenco di receivers e un elenco di processors per formare il flusso di dati.

Le sezioni seguenti descrivono ciascuno di questi elementi.

Ops Agent invia le metriche a Cloud Monitoring. Non puoi configurarlo per esportare le metriche in altri servizi.

Ricevitori di metriche

L'elemento receivers contiene un insieme di definizioni di receiver. Un ricevitore descrive da dove recuperare le metriche, ad esempio cpu e memory. Un ricevitore può essere condiviso tra più pipeline.

Struttura dei ricevitori di metriche

Ogni ricevitore deve avere un identificatore, RECEIVER_ID, e includere un elemento type. I tipi integrati validi sono:

  • hostmetrics
  • iis (solo Windows)
  • mssql (solo Windows)

Un ricevitore può anche specificare l'opzione di operazione collection_interval. Il valore è nel formato di una durata, ad esempio 30s o 2m. Il valore predefinito è 60s.

Ognuno di questi tipi di receiver raccoglie un insieme di metriche. Per informazioni sulle metriche specifiche incluse, consulta Metriche importate dai receiver.

Modifica dell'intervallo di raccolta nei receiver delle metriche

Alcuni workload critici potrebbero richiedere avvisi rapidi. Riducendo l'intervallo di raccolta delle metriche, puoi configurare avvisi più sensibili. Per informazioni su come vengono valutati gli avvisi, consulta Comportamento delle policy di avviso basate su metriche.

Ad esempio, il seguente receiver modifica l'intervallo di raccolta per le metriche host (l'ID del receiver è hostmetrics) dal valore predefinito di 60 secondi a 10 secondi:

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 10s

Puoi anche eseguire l'override dell'intervallo di raccolta per i receiver delle metriche di Windows iis e mssql utilizzando la stessa tecnica.

Metriche importate dai receiver

Le metriche importate da Ops Agent hanno identificatori che iniziano con il seguente pattern: agent.googleapis.com/GROUP. Il componente GROUP identifica un insieme di metriche correlate; ha valori come cpu, network e altri.

Il ricevitore hostmetrics

Il ricevitore hostmetrics importa i seguenti gruppi di metriche. Per saperne di più, consulta la sezione collegata per ogni gruppo nella pagina Metriche di Ops Agent.

Gruppo Metrica
cpu Carico della CPU a intervalli di 1 minuto
Carico della CPU a intervalli di 5 minuti
Carico della CPU a intervalli di 15 minuti
Utilizzo della CPU, con etichette per il numero e lo stato della CPU
Percentuale di utilizzo della CPU, con etichette per il numero e lo stato della CPU
disk Byte letti dal disco, con etichetta per il dispositivo
Byte scritti sul disco, con etichetta per il dispositivo
Tempo di I/O del disco, con etichetta per il dispositivo
Tempo di I/O ponderato del disco, con etichetta per il dispositivo
Operazioni in attesa sul disco, con etichetta per il dispositivo
Operazioni unite sul disco, con etichette per il dispositivo e la direzione
Operazioni sul disco, con etichette per il dispositivo e la direzione
Tempo di operazione sul disco, con etichette per il dispositivo e la direzione
Utilizzo del disco, con etichette per il dispositivo e lo stato
Utilizzo del disco, con etichette per il dispositivo e lo stato
gpu
Solo Linux; consulta Informazioni sulle metriche gpu per altre informazioni importanti. 		Numero attuale di byte di memoria GPU utilizzati, per stato
Quantità massima di memoria GPU, in byte, allocata dal processo
Percentuale di tempo nella durata del processo in cui uno o più kernel sono stati in esecuzione sulla GPU
Percentuale di tempo, dall'ultimo campione, in cui la GPU è stata attiva
interface
Solo per Linux 		Numero totale di errori di rete
Numero totale di pacchetti inviati sulla rete
Numero totale di byte inviati sulla rete
memory Memoria utilizzata, con etichetta per lo stato (buffered, cached, free, slab, used)
Percentuale di memoria utilizzata, con etichetta per lo stato (buffered, cached, free, slab, used)
network Numero di connessioni TCP, con etichette per porta e stato TCP
swap Operazioni di I/O di swap, con etichetta per la direzione
Byte di swap utilizzati, con etichette per dispositivo e stato
Percentuale di swap utilizzata, con etichette per dispositivo e stato
pagefile
Solo Windows 		Percentuale attuale di file di paging utilizzato per stato
processes Conteggio dei processi, con etichetta per lo stato
Conteggio dei processi con fork
I/O di lettura del disco per processo, con etichette per il nome del processo e altri
I/O di scrittura del disco per processo, con etichette per il nome del processo e altri
Utilizzo RSS per processo, con etichette per il nome del processo e altri
Utilizzo VM per processo, con etichette per il nome del processo e altri
Il ricevitore iis (solo Windows)

Il receiver iis (solo Windows) importa le metriche del gruppo iis. Per saperne di più, consulta la pagina Metriche dell'agente.

Gruppo Metrica
iis
Solo Windows 		Connessioni attualmente aperte a IIS
Byte di rete trasferiti da IIS
Connessioni aperte a IIS
Richieste effettuate a IIS
Il ricevitore mssql (solo Windows)

Il receiver mssql (solo Windows) importa le metriche del gruppo mssql. Per saperne di più, consulta la pagina Metriche di Ops Agent.

Gruppo Metrica
mssql
Solo Windows 		Connessioni attualmente aperte al server SQL
Transazioni totali al secondo del server SQL
Transazioni di scrittura al secondo del server SQL

Processori di metriche

L'elemento processor contiene un insieme di definizioni del processore. Un processore descrive le metriche del tipo di ricevitore da escludere. L'unico tipo supportato è exclude_metrics, che accetta un'opzione metrics_pattern. Il valore è un elenco di glob che corrispondono ai tipi di metriche di Ops Agent che vuoi escludere dal gruppo raccolto da un ricevitore. Ad esempio:

Processore di metriche di esempio

L'esempio seguente mostra il processore exclude_metrics fornito nelle configurazioni integrate. Questo processore fornisce un valore metrics_pattern vuoto, pertanto non esclude alcuna metrica.

processors:
  metrics_filter:
    type: exclude_metrics
    metrics_pattern: []

Per disattivare la raccolta di tutte le metriche di processo da parte di Ops Agent, aggiungi quanto segue al file config.yaml:

metrics:
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern:
      - agent.googleapis.com/processes/*

In questo modo, le metriche di processo vengono escluse dalla raccolta nel processore metrics_filter che si applica alla pipeline predefinita nel servizio metrics.

Servizio delle metriche

Il servizio delle metriche personalizza il livello di dettaglio per i log del modulo delle metriche di Ops Agent e collega i ricevitori e i processori delle metriche in pipeline. La sezione service contiene due elementi: log_level e pipelines.

Livello di dettaglio delle metriche

log_level, disponibile con le versioni di Ops Agent 2.6.0 e successive, personalizza il livello di dettaglio per i log del sottomodulo delle metriche di Ops Agent. Il valore predefinito è info. Le opzioni disponibili sono: error, warn, info, debug.

Pipeline di metriche

La sezione service ha un singolo elemento, pipelines, che può contenere più ID e definizioni di pipeline. Ogni definizione pipeline è costituita dai seguenti elementi:

  • receivers: obbligatorio per le nuove pipeline. Un elenco di ID ricevitore, come descritto in Ricevitori di metriche. L'ordine degli ID destinatario nell'elenco non è importante. La pipeline raccoglie i dati da tutti i ricevitori elencati.

  • processors: (Facoltativo) Un elenco di ID processore, come descritto in Processori di metriche. L'ordine degli ID di processo nell'elenco è importante. Ogni punto della metrica viene eseguito tramite i processori nell'ordine elencato.

Esempi di configurazioni delle metriche service

Una configurazione service ha la seguente struttura:

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

Per disattivare l'importazione integrata delle metriche host, ridefinisci la pipeline predefinita con un elenco receivers vuoto e senza processori. L'intera configurazione delle metriche è simile alla seguente:

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers: []

L'esempio seguente mostra la configurazione service integrata per Windows:

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers:
        - hostmetrics
        - iis
        - mssql
        processors:
        - metrics_filter

La seguente configurazione service personalizza il livello di dettaglio dei log per il sottomodulo delle metriche in modo che sia debug:

metrics:
  service:
    log_level: debug

Raccolta di log personali

Per impostazione predefinita, i log automatici di Fluent Bit di Ops Agent vengono inviati a Cloud Logging. Questi log possono includere molte informazioni e il volume aggiuntivo potrebbe aumentare i costi di utilizzo di Cloud Logging.

Puoi disattivare la raccolta di questi log interni, a partire dalla versione 2.44.0 di Ops Agent, utilizzando l'opzione default_self_log_file_collection.

Per disattivare la raccolta dei log automatici, aggiungi una sezione global al file di configurazione specificato dall'utente e imposta l'opzione default_self_log_file_collection sul valore false:

logging:  ...
metrics:  ...
global:
  default_self_log_file_collection: false

Configurazione della rotazione dei log

A partire dalla versione 2.31.0 di Ops Agent, puoi anche configurare la funzionalità di rotazione dei log dell'agente utilizzando i file di configurazione. Per saperne di più, consulta Configura la rotazione dei log in Ops Agent.