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.

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 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.

    Note that audit log-files are not automatically deleted: their eventual deletion is the responsibility of the administrator.

    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.