Google Chronicle

Google Chronicle Security Analytics

Synopsis

Creates a target that sends log data to Google Chronicle security analytics platform using the Chronicle Ingestion API. Supports OAuth2 service account authentication, custom labeling, batch processing, and multi-region deployment.

Schema

- name: <string>
  description: <string>
  type: gcpchronicle
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    project_id: <string>
    instance_id: <string>
    region: <string>
    default_log_type: <string>
    namespace: <string>
    log_text_field: <string>
    authentication_method: <string>
    service_account_credentials: <string>
    service_account_credentials_secret: <string>
    labels:
      - key: <string>
        value: <string>
    batch_size: <integer>
    timeout: <integer>
    request_timeout: <integer>
    field_format: <string>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration

The following fields are used to define the target:

Field	Required	Default	Description
name	Y		Target name
description	N	-	Optional description
type	Y		Must be gcpchronicle
pipelines	N	-	Optional post-processor pipelines
status	N	true	Enable/disable the target

Chronicle Configuration

Field	Required	Default	Description
project_id	Y	-	Google Cloud project ID
instance_id	Y	-	Chronicle instance ID (customer ID)
region	Y	-	Chronicle region: us, europe, asia
default_log_type	Y	-	Default log type for ingested logs
namespace	Y	-	Log namespace for organization
log_text_field	N	-	Event field to use as log text (if empty, uses JSON representation)
max_bytes	N	4194304 (4 MB)	Maximum size of a single request body or batch, in bytes

note

max_bytes caps the size of a single request body or batch. It behaves differently from max_size on the file-writing targets, and the difference is easy to get wrong:

• An explicit max_bytes: 0 IS honoured and removes the ceiling on targets that have no ceiling of their own. The value is read with Int64, which returns what you wrote — unlike max_size, which is read with MustInt64 and silently substitutes its default for a zero. Where a target has a fixed ceiling of its own, its page says so and a zero is clamped to that ceiling instead.
• A negative value is rejected at configuration time with max_bytes must not be negative.

The ceiling is validated when the target is built and enforced again on every batch, so a value the receiving service will refuse fails early rather than per request.

warning

For this target, max_bytes: 0 does not remove the ceiling. A 0, or any value above 4194304, is clamped to 4194304 bytes, the ceiling this target applies to a single request body, and the clamp is logged as a warning when the target starts. Leave max_bytes unset unless you need a smaller cap.

Authentication

Field	Required	Default	Description
authentication_method	N	credentials	Authentication method: credentials (inline JSON), secret (environment variable)
service_account_credentials	Y*	-	Google Cloud service account JSON credentials (inline)
service_account_credentials_secret	Y*	-	Environment variable name containing service account credentials

* = Conditionally required. When authentication_method is credentials (default), use service_account_credentials. When authentication_method is secret, use service_account_credentials_secret.

Custom Labels

Field	Required	Default	Description
labels	N	-	Array of custom labels to attach to log entries
labels[].key	Y	-	Label key
labels[].value	Y	-	Label value

Batch Configuration

Field	Required	Default	Description
batch_size	N	1000	Number of log entries to batch before sending (minimum 1)
timeout	N	30	Request timeout in seconds
request_timeout	N	30	HTTP request timeout in seconds

Processing

Field	Required	Default	Description
field_format	N	-	Data normalization format. See applicable Normalization section

Scheduling

See Scheduling and Pool Behavior for interval and cron fields shared by all targets.

Debug Options

Field	Required	Default	Description
debug.status	N	false	Enable debug logging
debug.dont_send_logs	N	false	Process logs but don't send to target (testing)

Details

The Google Chronicle target sends log data to Chronicle's security analytics platform using the Chronicle Ingestion API. Log events are batched and sent via HTTPS POST requests with OAuth2 authentication.

The target automatically parses JSON log messages and extracts structured data. A message that is not JSON is wrapped as a message field first, and that JSON object becomes the log text, so Chronicle receives {"message":"..."} rather than the original line. Set log_text_field: message to have the raw text arrive unchanged. Custom labels can be attached to all log entries for organizational purposes.

Chronicle Regions

Chronicle supports three regional endpoints (one of which must be specified via the required region field):

• us: United States - malachiteingestion-pa.googleapis.com
• europe: Europe - europe-malachiteingestion-pa.googleapis.com
• asia: Asia Southeast - asia-southeast1-malachiteingestion-pa.googleapis.com

Service Account Permissions

The service account must have the following IAM role:

• Chronicle API Writer (roles/chronicle.writer)

Or the following specific permission:

• malachite.ingestion.import

Prerequisites

1. A Google Cloud project with Chronicle enabled
2. Chronicle instance ID (customer ID)
3. Service account with Chronicle API Writer role
4. Service account JSON credentials
5. Network connectivity to Chronicle ingestion endpoints

note

The log_text_field parameter specifies which event field to use as the log text. If not specified or the field doesn't exist, the entire JSON event is used as log text.

warning

Service account credentials contain sensitive information. Use the secret authentication method with environment variables for production deployments instead of inline credentials.

Examples

Basic

Minimum configuration for Chronicle ingestion:

targets:
  - name: basic_chronicle
    type: gcpchronicle
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-12345678"
      region: "us"
      default_log_type: "GENERIC_EVENT"
      namespace: "production"
      service_account_credentials: |
        {
          "type": "service_account",
          "project_id": "my-gcp-project",
          "private_key_id": "key-id",
          "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
          "client_email": "chronicle-writer@my-gcp-project.iam.gserviceaccount.com",
          "client_id": "123456789",
          "auth_uri": "https://accounts.google.com/o/oauth2/auth",
          "token_uri": "https://oauth2.googleapis.com/token"
        }

With Environment Variable

Configuration using environment variable for credentials:

targets:
  - name: secure_chronicle
    type: gcpchronicle
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-12345678"
      region: "us"
      default_log_type: "GENERIC_EVENT"
      namespace: "production"
      authentication_method: "secret"
      service_account_credentials_secret: "CHRONICLE_SA_CREDENTIALS"

Europe Region

Configuration for European Chronicle instance:

targets:
  - name: europe_chronicle
    type: gcpchronicle
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-87654321"
      region: "europe"
      default_log_type: "GENERIC_EVENT"
      namespace: "production"
      authentication_method: "secret"
      service_account_credentials_secret: "CHRONICLE_SA_CREDENTIALS"

With Custom Labels

Configuration with custom labels for log categorization:

targets:
  - name: labeled_chronicle
    type: gcpchronicle
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-12345678"
      region: "us"
      default_log_type: "FIREWALL"
      namespace: "production"
      authentication_method: "secret"
      service_account_credentials_secret: "CHRONICLE_SA_CREDENTIALS"
      labels:
        - key: "environment"
          value: "production"
        - key: "application"
          value: "firewall"
        - key: "datacenter"
          value: "us-east-1"

With Log Text Field

Configuration using specific field as log text:

targets:
  - name: custom_field_chronicle
    type: gcpchronicle
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-12345678"
      region: "us"
      default_log_type: "SYSLOG"
      namespace: "production"
      log_text_field: "message"
      authentication_method: "secret"
      service_account_credentials_secret: "CHRONICLE_SA_CREDENTIALS"

High Volume

Configuration optimized for high-volume log ingestion:

targets:
  - name: highvolume_chronicle
    type: gcpchronicle
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-12345678"
      region: "us"
      default_log_type: "GENERIC_EVENT"
      namespace: "production"
      batch_size: 5000
      timeout: 60
      request_timeout: 60
      authentication_method: "secret"
      service_account_credentials_secret: "CHRONICLE_SA_CREDENTIALS"

With Normalization

Configuration using field normalization:

targets:
  - name: normalized_chronicle
    type: gcpchronicle
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-12345678"
      region: "us"
      default_log_type: "GENERIC_EVENT"
      namespace: "production"
      field_format: "ecs"
      authentication_method: "secret"
      service_account_credentials_secret: "CHRONICLE_SA_CREDENTIALS"

With Pipeline

Using a pipeline for additional log processing:

targets:
  - name: pipeline_chronicle
    type: gcpchronicle
    pipelines:
      - enrich_logs
    properties:
      project_id: "my-gcp-project"
      instance_id: "customer-12345678"
      region: "us"
      default_log_type: "GENERIC_EVENT"
      namespace: "production"
      authentication_method: "secret"
      service_account_credentials_secret: "CHRONICLE_SA_CREDENTIALS"

Troubleshooting

This section covers the errors you are most likely to see with the gcpchronicle target, what causes each one, and how to fix it.

Where to look:

• Director logs. Target errors are tagged with the target name and carry "Section":"SenderPool". The part after Reason: or after the last colon is the actual cause.
• The target's connection status in the web interface. It shows the same reason as the log line, prefixed with connection failed for <target name>:.

See Target Delivery Errors for how Director logs and retries target failures.

Two facts about this target shape every entry below. The target asks Google for a token while it starts, so a missing, malformed, or revoked service account key is reported at startup and shows in the connection status. Your ingestion permission is not checked then. Google checks it on the first batch, so the target can report a healthy connection while every flush fails.

Which permission is missing?

Match the error you see against this table first.

Error text	Missing role or permission	Resource
chronicle api returned status 403	The Chronicle ingestion role roles/chronicle.writer, or the single permission malachite.ingestion.import	The Chronicle instance named in instance_id
chronicle api returned status 403 or status 404 with the role already granted	None. The Chronicle ingestion API is not enabled on the project, or project_id, instance_id, and region do not describe one tenant	The project named in project_id
chronicle api returned status 401	The OAuth2 scope https://www.googleapis.com/auth/malachite-ingestion for the service account, or the account is disabled	The service account
failed to get oauth2 token: ...	None. The key itself cannot mint a token	The service account key

This page names roles/chronicle.writer. Another reference in the product names roles/chronicle.editor for the same operation, so grant whichever role your Chronicle instance accepts. The target only ever calls the log import operation, so any role that allows that import is enough.

note

Director keeps retrying while a role is missing, so delivery resumes on the next attempt once the grant is in place. No restart is needed.

"failed to get oauth2 token"

[Error] [director] [target-<target id>] [basic_chronicle] Failed to reinitialize target "basic_chronicle" (attempt 1). Reason: failed to get oauth2 token: oauth2: cannot fetch token: 400 Bad Request
Response: ...

Cause: the target asks Google for a token before it accepts any data, and that request was refused. The response body on the second line typically carries invalid_grant, which means the key was rotated, deleted, or disabled, or the service account itself is disabled. A badly skewed host clock typically produces the same body. The same wrapper with private key should be a PEM or plain PKCS1 or PKCS8 or private key is invalid means the private_key value in the key JSON is corrupt, usually because YAML quoting broke its line breaks.

Fix: download a fresh key for the service account and paste it with a YAML block scalar, as the Basic example on this page does. Confirm the account is enabled, and check that the host clock is synchronized.

The same text appears as Sender worker N Finalize failed on flush for target "basic_chronicle": failed to get oauth2 token: ... when the key is revoked after startup. The cached token is used until it expires, so the failure can surface up to an hour after the change. Nothing is lost either way. Incoming data waits in the Director queue and is delivered once the token request succeeds.

"failed to create credentials"

Failed to reinitialize target "basic_chronicle" (attempt 2). Reason: failed to create credentials: invalid character '/' looking for beginning of value

Cause: the value is not a complete Google service account key. The text after the colon says which way it is wrong.

Text	Meaning
invalid character '/' looking for beginning of value	A file path was pasted instead of the key. Neither authentication method reads files
unexpected end of JSON input	The value is empty, or only part of the key was pasted
invalid character '\n' in string literal	The line breaks inside private_key were not preserved
missing 'type' field in credentials, or unknown credential type: ...	The JSON parses but is not a service account key, for example a user credential or a client secret file

Fix: paste the whole key JSON under service_account_credentials using a block scalar, or point secret mode at an environment variable that holds the whole key. Only a key whose type is service_account works.

Nothing is sent while this persists. It is retried until you fix it, and queued data waits.

"failed to resolve service account credentials" or "environment variable ... not found or empty"

Failed to reinitialize target "secure_chronicle" (attempt 4). Reason: failed to resolve service account credentials secret: environment variable "CHRONICLE_SA_CREDENTIALS" not found or empty
Failed to reinitialize target "basic_chronicle" (attempt 7). Reason: failed to resolve service account credentials: credential: env variable "CHRONICLE_SA_CREDENTIALS" is not set

Cause: the first form belongs to secret mode. When the property value is not JSON, it is read as the name of an environment variable, and that variable is unset or empty for the Director service. A file path put in the property ends here too, because a path is not JSON either. The second form means a ${VAR} or $secret{...} reference in either property could not be resolved. The part after credential: says why.

Text	Meaning
env variable "..." is not set	The variable is not exported to the Director service user. A variable set in your own shell is not visible to the service
failed to parse token "...": ...	The $secret{...} syntax is malformed
store "..." not found in configuration	The store name in $secret{...} does not match a configured credential store
provider type "..." is not registered, or no credentials configured	The store's provider type is misspelled, or no credential store is defined at all
path reference "..." names no path	A $path{...} reference points at nothing. The resolved value is still expected to be the key JSON, not a file to read

Fix: for an unset environment variable, export it for the Director service user with the full key JSON as its value, then restart Director so it inherits it, because a running process does not see a variable exported after it started. For a $secret{...} reference or a store definition, correct the reference or the store and the next retry picks the value up, with no restart. Nothing is sent while this persists, and nothing is lost.

"chronicle api returned status 403"

Sender worker 2 Finalize failed on flush for target "basic_chronicle": chronicle api returned status 403: ...

Cause: Google accepted your token and refused the request. The body typically names PERMISSION_DENIED. Either the service account has no ingestion role on the instance, or the Chronicle ingestion API is not enabled on project_id, or the account belongs to a different Chronicle tenant than instance_id. A wrong region looks the same: all three regional hosts resolve and accept connections, so you get a refusal rather than a network error.

Fix: grant the role from the table above, enable the Chronicle ingestion API on the project, and confirm that project_id, instance_id, and region all describe the same Chronicle tenant.

No data is lost. Director discards the failed batch from memory, keeps the payloads queued, and redelivers them about every five seconds after the target reinitializes. Expect the queue to grow until the role is in place.

"chronicle api returned status 400", "413", or "422"

Sender worker 1 Finalize failed on flush for target "basic_chronicle": record rejected by target: chronicle api returned status 400: ...
Sender worker 1 dropping <payload> for target "basic_chronicle" after 4 rejected flush attempts — the endpoint refuses this batch deterministically, so its records are given up on

Cause: these three statuses are treated as a permanent rejection of the batch content, which the record rejected by target: prefix marks. A 400 typically names INVALID_ARGUMENT, and the usual trigger is a default_log_type your Chronicle instance does not know, or a namespace or label value it refuses. A wrong log type typically appears here as a 400, but it can also come back as a 404, which is retried instead of dropped. A 413 means the request body was larger than the endpoint accepts.

Fix: check default_log_type against the log types your Chronicle instance accepts, and read the response body in the log line for the field it names. On a 413, lower batch_size or max_bytes.

This is the one case where this target loses data. After four flush attempts the whole batch, up to batch_size events, is given up on. The records are not counted in the target's dropped statistics, so watch the log for the dropping ... after 4 rejected flush attempts line. Every other status, 401, 404, 429, and 5xx included, is retried until it succeeds.

"record size ... exceeds configured max_bytes"

Sender worker 3 execute() failed for basic_chronicle: record rejected by target: record size 4210012 exceeds configured max_bytes 4194229

Cause: one event on its own is too large for a request. The second number is the room left for entries once the request envelope is accounted for, so it is slightly smaller than the max_bytes you configured. Two things make an event larger than it looks. A JSON event is embedded as a string, so every quotation mark and backslash costs one extra byte, and an event that is not JSON is wrapped before it is measured.

Fix: trim or split the event in a pipeline. max_bytes cannot be raised past 4194304, so a single event above that ceiling can never be delivered.

That one record is dropped after four deliveries. The rest of the batch is unaffected.

Two related messages appear when the target starts. max_bytes must exceed the 75-byte chronicle request envelope, got 64 means max_bytes is positive but smaller than the request envelope, so raise it or remove the setting. A warning ending and was clamped to it; set a value between 1 and 4194304 to silence this means max_bytes is 0 or above 4194304. The value is then clamped to 4194304 bytes, the ceiling the target applies to one request body, because a 0 does not remove that ceiling here. batch_size is clamped the same way, at 10000 records. Neither clamp drops anything.

"chronicle api returned status 429"

Sender worker 0 Finalize failed on flush for target "basic_chronicle": chronicle api returned status 429: ...

Cause: Google is throttling your ingestion. The body typically names RESOURCE_EXHAUSTED. The target neither limits its own rate nor retries by itself, so every 429 becomes a failed flush.

Fix: nothing in the target needs changing for a short burst. If it persists, raise the ingestion quota on the Chronicle instance or spread the load over more targets.

No data is lost. Payloads are redelivered about every five seconds until Google accepts them, so the queue grows while the throttling lasts.

"failed to send request" or "failed to read response"

Sender worker 0 Finalize failed on flush for target "basic_chronicle": failed to send request: Post "https://malachiteingestion-pa.googleapis.com/v1alpha/projects/my-gcp-project/instances/customer-12345678/logTypes/GENERIC_EVENT:import": dial tcp: lookup malachiteingestion-pa.googleapis.com: no such host

Cause: Director could not complete the HTTPS request. The hostname in the message tells you which endpoint failed: oauth2.googleapis.com for the token, or the regional ingestion host for the batch.

Text	Meaning
dial tcp: lookup ...: no such host	DNS on the Director host cannot resolve the endpoint
i/o timeout, or connection refused	A firewall is blocking outbound 443 to the endpoint
context deadline exceeded	The request did not finish within timeout, 30 seconds by default
context deadline exceeded (Client.Timeout exceeded while awaiting headers)	The same, bounded by request_timeout
tls: failed to verify certificate: x509: certificate signed by unknown authority	A TLS-inspecting proxy is in the path. The target has no TLS options of its own and trusts the operating system store
proxyconnect tcp: ...	The proxy named in HTTPS_PROXY refused the connection or does not answer
failed to read response: read tcp ...: connection reset by peer	The connection dropped while the response was being read

Fix: allow outbound 443 from the Director host to oauth2.googleapis.com and to the regional host for your region, listed under Chronicle Regions above. Exempt both hosts from TLS inspection, or install the proxy's CA certificate at the operating system level. Set HTTPS_PROXY and NO_PROXY for the Director service user, not in your own shell. Raise timeout and request_timeout together if the link is slow.

All of these are retried until they succeed, so nothing is lost.

"ValidateConfig failed for target ..."

ValidateConfig failed for target "basic_chronicle": invalid region: EU

Cause: the configuration was rejected before anything was sent. Director re-checks it about every 30 seconds, so the message repeats until you change the configuration.

Reason	Fix
project_id is required, instance_id is required, default_log_type is required, or namespace is required	Set the field. All four are required, and namespace has no default
invalid region: ...	region accepts exactly us, europe, or asia. The match is case-sensitive, so US, EU, and europe-west1 are all rejected
invalid authentication_method: ...	authentication_method accepts exactly credentials or secret, in lower case
service_account_credentials is required when using credentials authentication	Set the inline key, or a ${VAR} or $secret{...} reference to it
service_account_credentials_secret is required when using secret authentication	Set the environment variable name, or a reference that resolves to the key JSON
batch_size must be greater than 0, got ...	Remove the setting to use the default of 1000, or set a value from 1 to 10000
max_bytes must not be negative, got ...	Remove the setting, or use a value from 1 to 4194304

Nothing is sent while the configuration is invalid, and queued data waits. Fix the reason shown and the next check picks it up. Restarting Director is not required.

The target is healthy but nothing arrives in Chronicle

Check these in order.

1. debug.dont_send_logs is enabled. Events are processed but never posted. No error is logged and no delivery counter moves. The notice Log sending is disabled for this target is written only when debug.status is also true, so with dont_send_logs on its own there is nothing in the log at all. Remove the flag.

2. Batches are being dropped. Search the log for dropping ... after 4 rejected flush attempts with the target name. See the entry on 400, 413, and 422 above.

3. The data is there but does not look like what you sent. A message that is not JSON is wrapped before it is sent, so Chronicle parsers that expect raw syslog or CEF do not match it. Set log_text_field: message for raw text sources.

4. log_text_field names a field the event does not carry. The whole JSON event is used as the log text instead, and the delivery still counts as a success. Field names are matched case-sensitively.

5. A label is missing from the entries. A label whose key or value is empty is dropped from the entry, and nothing is logged.

6. Events carry their own __logType. The entry's log type is overridden, but the request is still sent to the log type in default_log_type. Whether Chronicle honours the per-entry value is not something to rely on. Route different log types to separate targets instead.