3.1 MGM API Concepts

This section describes concepts basic to the NDB Cluster MGM API.

• NdbMgmHandle

• Working with Log Events

• Structured Log Events

NdbMgmHandle

Each MGM API function needs a management server handle of type NdbMgmHandle. This handle is created by calling the function ndb_mgm_create_handle() and freed by calling ndb_mgm_destroy_handle().

See ndb_mgm_create_handle(), and ndb_mgm_destroy_handle(), for more information about these two functions.

Important

You should not share an NdbMgmHandle between threads. While it is possible to do so (if you implement your own locks), this is not recommended; each thread should use its own management server handle.

A function can return any of the following:

• An integer value, with a value of -1 indicating an error.

• A nonconstant pointer value. A NULL value indicates an error; otherwise, the return value must be freed by the programmer.

• A constant pointer value, with a NULL value indicating an error. The returned value should not be freed.

Error conditions can be identified by using the appropriate error-reporting functions ndb_mgm_get_latest_error() and ndb_mgm_error().

Here is an example using the MGM API (without error handling for brevity's sake):

NdbMgmHandle handle= ndb_mgm_create_handle();
ndb_mgm_connect(handle,0,0,0);
struct ndb_mgm_cluster_state *state= ndb_mgm_get_status(handle);
for(int i=0; i < state->no_of_nodes; i++)
{
  struct ndb_mgm_node_state *node_state= &state->node_states[i];
  printf("node with ID=%d ", node_state->node_id);

  if(node_state->version != 0)
    printf("connected\n");
  else
    printf("not connected\n");
}
free((void*)state);
ndb_mgm_destroy_handle(&handle);

Working with Log Events

Data nodes and management servers both regularly and on specific occasions report on various log events that occur in the cluster. These log events are written to the cluster log. Optionally an MGM API client may listen to these events using the method ndb_mgm_listen_event(). Each log event belongs to a category ndb_mgm_event_category) and has a severity ndb_mgm_event_severity associated with it. Each log event also has a level (0-15) associated with it.

Which log events that come out is controlled with ndb_mgm_listen_event(), ndb_mgm_set_clusterlog_loglevel(), and ndb_mgm_set_clusterlog_severity_filter().

This is an example showing how to listen to events related to backup:

int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 };
int fd = ndb_mgm_listen_event(handle, filter);

Structured Log Events

Handling of structured log events in the MGM API involves the following steps:

1. Create an NdbLogEventHandle using ndb_mgm_create_logevent_handle().

2. Wait for and store log events using ndb_logevent_get_next().

3. The log event data is available in the structure ndb_logevent. The data which is specific to a particular event is stored in a union between structures; use ndb_logevent::type to decide which structure is valid.

The following sample code demonstrates listening to events related to backups:

int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 };
NdbLogEventHandle le_handle= ndb_mgm_create_logevent_handle(handle, filter);
struct ndb_logevent le;
int r= ndb_logevent_get_next(le_handle, &le, 0);
if(r < 0)
  /*  error  */
else if(r == 0)
  /*  no event  */

switch(le.type)
{
  case NDB_LE_BackupStarted:
    ... le.BackupStarted.starting_node;
    ... le.BackupStarted.backup_id;
    break;
  case NDB_LE_BackupFailedToStart:
    ... le.BackupFailedToStart.error;
    break;
  case NDB_LE_BackupCompleted:
    ... le.BackupCompleted.stop_gci;
    break;
  case NDB_LE_BackupAborted:
    ... le.BackupStarted.backup_id;
    break;
  default:
    break;
}

For more information, see Section 3.2.1, “Log Event Functions”.

Available log event types are listed in The Ndb_logevent_type Type, as well as in the file /storage/ndb/include/mgmapi/ndb_logevent.h in the NDB Cluster sources.