Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Auditing

      +
      Couchbase Server provides event-auditing, sending output to a log-file.

      Introduction to Auditing

      The Couchbase Server auditing facility recognizes specific, server-generated events, which can be logged. The output is written to a log-file, which is periodically rotated.

      Audit Event-Types

      Events generated by Couchbase Server are of two kinds:

      • Admin events, which track administrative and configuration changes to the cluster.

      • Data events, which track attempts to access and change data.

      Note that event-auditing occurs on a per node basis: each node captures its own events only. If a cluster-wide record is needed, the individual per node records must be manually consolidated by the administrator.

      This page explains frequently used audit fields, and gives examples of record-structures. For information on managing auditing, see Manage Auditing. See the reference page Audit Event Reference, for a complete list of events that can be audited.

      Audit Fields

      The table below lists frequently used audit fields, with corresponding descriptions. Note that different event-types generate different field-subsets.

      Field Type Description

      "id"

      Integer

      The unique identifier for the event. For example, 20480, 8192, or 28672.

      "name"

      String

      The name of the event. For example, "login success", "User was deleted", or "A N1QL UPSERT statement was executed".

      "description"

      String

      A description for the event. For example, "Unsuccessful attempt to login to couchbase cluster", "Node was removed from the cluster", or "Bucket was created".

      "real_userid"

      Object

      Contains key-value pairs for "domain" (specifying "local"; "external"; "builtin" — for the administrator who set up the cluster; or "rejected" — for a user who has been denied access); and "user" (specifying the id of the user who generated the event).

      "local"

      Object

      Contains key-value pairs for "ip" and incoming "port", for the node on which the event was processed.

      "remote"

      Object

      Contains key-value pairs for "ip" and outgoing "port", for the node on which the event-request was dispatched.

      "timestamp"

      UTC timestamp

      The UTC timestamp for the event’s generation (for example, "2020-01-29T08:02:07.476-08:00": see Date and Time Formats).

      Saving and Pruning Audit Records

      When auditing is enabled, logged events are written to a default file, named audit.log. After an administrator-specified period — which must be a minimum of 15 minutes and a maximum of 7 days — this file is closed, and is saved under a modified name that features a timestamp corresponding to the time of saving. A new, empty audit.log file is created and saved when a new audit event is generated. Note that this rotation may happen earlier if the file reaches its maximum size of 20MB. For instructions on configuring the file’s rotation time, see Manage Auditing.

      By default, Couchbase Server does not automatically delete rotated audit log files. Over time, these log files can consume disk space on your nodes. You can choose to have Couchbase Server remove rotated audit logs after a period of time by using the Configure Auditing REST-API’s pruneAge parameter. You can also use an external tool or script to periodically remove audit files directly from the log directory.

      Sample Audit Records

      A number of sample audit records are presented below.

      Login

      An audit record for a successful login might appear as follows:

      {
  "description": "Successful login to couchbase cluster",
  "id": 8192,
  "local": {
    "ip": "10.144.210.101",
    "port": 8091
  },
  "name": "login success",
  "real_userid": {
    "domain": "local",
    "user": "testUser"
  },
  "remote": {
    "ip": "10.144.210.1",
    "port": 53322
  },
  "roles": [
    "admin"
  ],
  "sessionid": "ba2760cee506d0293a8b4a0bf83687b807329667",
  "timestamp": "2021-02-09T14:44:17.938Z"
}

      In this example, a user named testUser has successfully logged into a Couchbase cluster-node whose IP address is 10.144.210.101.

      Login Failure

      The following audit-record indicates that a login attempt failed:

      {
  "description": "Unsuccessful attempt to login to couchbase cluster",
  "id": 8193,
  "local": {
    "ip": "10.144.210.101",
    "port": 8091
  },
  "name": "login failure",
  "real_userid": {
    "domain": "rejected",
    "user": "newUser"
  },
  "remote": {
    "ip": "10.144.210.1",
    "port": 53348
  },
  "timestamp": "2021-02-09T14:45:34.934Z"
}

      This record indicates that a user named newUser incurred an Unsuccessful attempt to login to couchbase cluster.

      Bucket Creation

      The audit-record below corresponds to the creation of a bucket.

      {
  "bucket_name": "testBucket",
  "description": "Bucket was created",
  "id": 8201,
  "local": {
    "ip": "10.144.231.102",
    "port": 8091
  },
  "name": "create bucket",
  "props": {
    "compression_mode": "passive",
    "conflict_resolution_type": "seqno",
    "durability_min_level": "none",
    "eviction_policy": "value_only",
    "flush_enabled": false,
    "max_ttl": 0,
    "num_replicas": 1,
    "num_threads": 3,
    "purge_interval": "undefined",
    "ram_quota": 268435456,
    "replica_index": false,
    "storage_mode": "couchstore"
  },
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "remote": {
    "ip": "10.144.231.1",
    "port": 53837
  },
  "sessionid": "3f8472056c30014d32f19aca0bb22b10d5cefbee",
  "timestamp": "2022-08-23T10:05:34.489Z",
  "type": "membase"
}

      This record indicates that a Bucket was created; that the bucket was named testBucket; and that its eviction-policy was defined as value_only. The bucket was created by the user Administrator.

      Bucket TTL Modification

      The audit record below corresponds to the modification of Bucket TTL, for the bucket created immediately above.

      {
  "bucket_name": "testBucket",
  "description": "Bucket was modified",
  "id": 8202,
  "local": {
    "ip": "10.144.210.101",
    "port": 8091
  },
  "name": "modify bucket",
  "props": {
    "compression_mode": "passive",
    "durability_min_level": "none",
    "eviction_policy": "value_only",
    "flush_enabled": false,
    "max_ttl": 100000,
    "num_replicas": 1,
    "num_threads": 3,
    "purge_interval": "undefined",
    "ram_quota": 268435456,
    "storage_mode": "couchstore"
  },
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "remote": {
    "ip": "10.144.210.1",
    "port": 53397
  },
  "sessionid": "eb1411eaa5eb041ea07fb86ffe93a94a59f8e8e2",
  "timestamp": "2021-02-09T14:48:14.653Z",
  "type": "membase"
}

      This record indicates that the bucket testBucket was modified. The max_ttl is now represented as 100000 seconds.

      User Creation

      The audit-record below corresponds to the creation of a user.

      {
  "description": "User was added or updated",
  "full_name": "",
  "groups": [],
  "id": 8232,
  "identity": {
    "domain": "local",
    "user": "clusterUser"
  },
  "local": {
    "ip": "10.144.210.101",
    "port": 8091
  },
  "name": "set user",
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "reason": "added",
  "remote": {
    "ip": "10.144.210.1",
    "port": 53444
  },
  "roles": [
    "cluster_admin"
  ],
  "sessionid": "eb1411eaa5eb041ea07fb86ffe93a94a59f8e8e2",
  "timestamp": "2021-02-09T14:50:38.256Z"
}

      This record indicates that a user named clusterUser was created by Administrator; and that the user was given the role of cluster_admin.

      Index Creation

      The following audit-record indicates that a Full Text Index was created or updated:

      {
  "description": "FTS index was created/Updated",
  "id": 24577,
  "index_name": "testIndex",
  "local": {
    "ip": "127.0.0.1",
    "port": "8094"
  },
  "name": "Create/Update index",
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "remote": {
    "ip": "127.0.0.1",
    "port": "39575"
  },
  "timestamp": "2021-02-09T15:20:49.953Z"
}

      This record indicates that an FTS index named testIndex was created or updated.

      Filterable and Non-Filterable Events

      Eventing for each cluster-node is disabled by default; and can be explicitly enabled. When enablement has occurred, a default subset of Couchbase Server-events is audited, with records duly concatenated to the end of the audit.log file. Some of the events in this default subset are non-filterable; meaning that while auditing is enabled for the node, all the events in the subset are always recorded, and cannot be selectively disabled.

      Other events, including ones that are initially disabled, are filterable; meaning that while auditing is enabled for the node, each can be individually enabled or disabled by the administrator. Note also that optionally, filterable events can be ignored for specified users.

      For information on how to filter events, see Manage Auditing.

      Event Tables

      See the reference page Audit Event Reference, for a complete list of events that can be audited.