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

System Events

      +
      Couchbase Server logs system events for the cluster, and allows their retrieval.

      Understanding System Events

      System events are generated to record significant occurrences on the cluster. Events are provided for the Cluster Manager, the Data Service, the Index Service, the Search Service, the Eventing Service, the Backup Service, and the Analytics Service. Events are also generated for XDCR, security, and Views.

      Each event is provided as a JSON document containing a number of key-value pairs: some key-value pairs are included in all system events, others are specific to the service for which the event is generated. Each key-value pair provides definitive information on the event.

      Each system event for a given service is of a certain type; and this is indicated by key-value pairs that respectively provide an ID and a description. Additionally, each event-type is considered to be at a particular level of severity: supported levels are info, warn, error, and fatal.

      The goal of system-event generation is to provide users with a clear account of what occurs on the cluster: however, system events are not intended to provide detailed, diagnostic information (regarding which, see the reference to Logging, provided below).

      System events are recorded in a system log, which is maintained by the Cluster Manager. Each node in the cluster has a copy of the system log; and each log is kept up to date by means of gossip replication between the nodes. (See Metadata Management, for information on gossip replication.) The default number of systems logs stored is 10k — the log is rotated by the Cluster Manager. Note that the size can be modified: the smallest possible value is 3k, the highest is 20k. Retrieval and modification of the current size are accomplished by means of the /internalSettings endpoint: for examples, see Managing Internal Settings. Note also that the current size can only be changed when all cluster-nodes are running Couchbase Server Version 7.1 or higher.

      System events do not need to be explicitly enabled by the administrator: they are collected by default, and can be retrieved by the administrator as required. Retrieval is accomplished by means of the REST API, two methods of retrieval being supported:

      • Batch retrieval. Either all events or a specified number are retrieved in a single array, either from the beginning of the system log or from a specified time.

      • Dynamic retrieval. Each event is returned as it happens.

      For detailed information on the REST API for system events, see Getting System Events.

      Note that system events are different from, and should not be confused with, two other facilities provided by Couchbase Server:

      • Auditing. Audit events are generated by Couchbase Server to maintain a record of security-related occurrences across the cluster. Auditing must be specifically enabled by the administrator. Audit events can be filtered, so that only a desirable subset is generated. For information, see Auditing.

      • Logging. This provides a series of per node log files, the content for each of which is periodically incremented by a particular service or process, to maintain an account of occurrences and results. Logging allows detailed system diagnostics to be performed. For information, see Manage Logging.

      System-Event Structure

      Every system event always contains the following fields.

      Field Value Type Description

      timestamp

      string

      Date and time of the event in UTC iso-8601 format, which is YYYY-MM-DDThh:mm:ss:SSSZ. For more information, see Date and Time Formats.

      component

      string

      Name of the service generating the event. This can be ns_server, query, indexing, search, eventing, analytics, backup, xdcr, data, security, or views.

      severity

      string

      The degree of significance of the type of occurrence. This can be info, warn, error, or fatal.

      id

      unsigned integer

      The identifier for the type of occurrence. For example, whenever a bucket is created, the Data Service generates a Bucket created event, whose id 8192.

      description

      string

      The description of the type of occurrence. For example, whenever a bucket is created, the Data Service generates an event whose description is Bucket created.

      uuid

      string

      A universally unique identifier provided for each specific instance of an occurrence-type. For example, if two buckets are created, two Bucket created events are generated by the Data Service, both with the id 8192, and each with its own uuid.

      Note that all system events contain additional fields that are specific to the service that is generating the event. Examples of system-event structure can be found in the REST API reference page, Getting System Events.

      System Events and Upgrade

      System-event provision is supported only when every node in the cluster is running a version of Couchbase Server that is 7.1 or later. If any node is running a version that is less than 7.1, any attempt to return system events returns the message Not found.

      Returning System Events

      System events can be returned by means of the REST API. For information, see Getting System Events. In Couchbase Server 7.1, system events cannot be returned by means either of the CLI or the UI.

      See Also

      A complete list of system events is provided in System Event Reference. Information on the REST API for returning system events is provided in Getting System Events.