A newer version of this documentation is available.

View Latest

Analytics Configuration REST API

      +

      Overview

      The Analytics Configuration REST API is provided by the Analytics service. This API enables you to configure Analytics nodes and clusters.

      The API schemes and host URLs are as follows:

      where node is the host name or IP address of a node running the Analytics service.

      Version information

      Version : 7.2

      Consumes

      • application/x-www-form-urlencoded

      • application/json

      Produces

      • application/json

      Paths

      This section describes the operations available with this REST API.

      View Service-Level Parameters

      GET /analytics/config/service

      Description

      Views service-level parameters, which apply to all nodes running the Analytics service.

      Responses

      HTTP Code Description Schema

      200

      Success. Returns an object listing the configurable service-level parameters and their current values.

      401

      Unauthorized. The user name or password may be incorrect.

      Returns an object containing an error message. Refer to Error Codes.

      object

      Security

      Type Name

      basic

      Example HTTP request

      Curl request
      curl -v -u Administrator:password \
           http://localhost:8095/analytics/config/service

      Example HTTP response

      Response 200
      {
        "activeMemoryGlobalBudget" : 67108864,
        "activeStopTimeout" : 3600,
        "activeSuspendTimeout" : 3600,
        "analyticsBroadcastDcpStateMutationCount" : 10000,
        "analyticsHttpRequestQueueSize" : 256,
        "analyticsHttpThreadCount" : 16,
        "bindAddress" : null,
        "bindToHost" : false,
        "clusterConnectRetries" : 5,
        "collectDcpStateFromNodesTimeout" : 600,
        "compilerFramesize" : 32768,
        "compilerGroupmemory" : 33554432,
        "compilerJoinmemory" : 33554432,
        "compilerParallelism" : 0,
        "compilerSortParallel" : false,
        "compilerSortmemory" : 33554432,
        "compilerWindowmemory" : 33554432,
        "coresMultiplier" : 3,
        "dcpBufferAckWatermark" : 20,
        "dcpChannelReconnectRemoteIdleSeconds" : 120,
        "dcpConnectionBufferSize" : 10485760,
        "deadlockWatchdogHaltDelaySeconds" : 120,
        "deadlockWatchdogPollSeconds" : 300,
        "jobHistorySize" : 10,
        "jobQueueCapacity" : 4096,
        "jvmArgs" : null,
        "logLevel" : "DEBUG",
        "maxWebRequestSize" : 209715200,
        "netBufferCount" : 1,
        "netThreadCount" : 1,
        "rebalancePullDatasetSizeFrequency" : 5,
        "remoteLinkConnectTimeoutSeconds" : 60,
        "remoteLinkSocketTimeoutSeconds" : 60,
        "requestsArchiveSize" : 50,
        "resultSweepThreshold" : 60000,
        "resultTtl" : 86400000,
        "storageBuffercacheMaxopenfiles" : 2147483647,
        "storageBuffercachePagesize" : 131072,
        "storageCompressionBlock" : "snappy",
        "storageMemorycomponentNumcomponents" : 2,
        "storageMemorycomponentPagesize" : 131072,
        "storageWriteRateLimit" : 0,
        "threaddumpFrequencySeconds" : 300,
        "threaddumpLogLevel" : "DEBUG",
        "traceCategories" : [ ],
        "txnDatasetCheckpointInterval" : 3600
      }

      Modify Service-Level Parameters

      PUT /analytics/config/service

      Description

      Modifies service-level parameters, which apply to all nodes running the Analytics service.

      For the configuration changes to take effect, you must restart the Analytics cluster using the Cluster Restart API.

      Parameters

      By default, the API accepts parameters using the application/x-www-form-urlencoded MIME type. You can specify the application/json MIME type using the Content-Type header of the PUT request.

      Type Name Description Schema

      Body

      Service
      optional

      An object specifying one or more of the configurable service-level parameters.

      Responses

      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. Unknown parameter or incorrect value.

      401

      Unauthorized. The user name or password may be incorrect.

      Returns an object containing an error message. Refer to Error Codes.

      object

      Security

      Type Name

      basic

      Example HTTP request

      Curl request
      curl -v -u Administrator:password -X PUT \
           -d jobHistorySize=5 \
           http://localhost:8095/analytics/config/service

      View Node-Specific Parameters

      GET /analytics/config/node

      Description

      Views node-specific parameters, which apply to the node receiving the request.

      Responses

      HTTP Code Description Schema

      200

      Success. Returns an object listing the configurable node-level parameters and their current values.

      401

      Unauthorized. The user name or password may be incorrect.

      Returns an object containing an error message. Refer to Error Codes.

      object

      Security

      Type Name

      basic

      Example HTTP request

      Curl request
      curl -v -u Administrator:password \
           http://localhost:8095/analytics/config/node

      Example HTTP response

      Response 200
      {
        "jvmArgs" : null,
        "storageBuffercacheSize" : 325320704,
        "storageMemorycomponentGlobalbudget" : 325320704
      }

      Modify Node-Specific Parameters

      PUT /analytics/config/node

      Description

      Views node-specific parameters, which apply to the node receiving the request.

      For the configuration changes to take effect, you must restart the node using the Node Restart API, or restart the Analytics cluster using the Cluster Restart API.

      Parameters

      By default, the API accepts parameters using the application/x-www-form-urlencoded MIME type. You can specify the application/json MIME type using the Content-Type header of the PUT request.

      Type Name Description Schema

      Body

      Node
      optional

      An object specifying one or more of the configurable node-level parameters on this node.

      Responses

      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. Unknown parameter or incorrect value.

      401

      Unauthorized. The user name or password may be incorrect.

      Returns an object containing an error message. Refer to Error Codes.

      object

      Security

      Type Name

      basic

      Example HTTP request

      Curl request
      curl -v -u Administrator:password -X PUT \
           -d storageBuffercacheSize=162660352 \
           http://localhost:8095/analytics/config/node

      Definitions

      This section describes the properties consumed and returned by this REST API.

      Service

      Name Description Schema

      activeMemoryGlobalBudget
      optional

      The memory budget (in bytes) for the active runtime.
      Default : 67108864

      integer (int32)

      activeStopTimeout
      optional

      The maximum time (in seconds) to wait for a graceful stop of an active runtime.
      Default : 3600

      integer (int32)

      activeSuspendTimeout
      optional

      The maximum time (in seconds) to wait for a graceful suspend of an active runtime.
      Default : 3600

      integer (int32)

      analyticsBroadcastDcpStateMutationCount
      optional

      The number of processed mutations after which the DCP state is broadcast to storage
      Default : 10000

      integer (int32)

      analyticsHttpRequestQueueSize
      optional

      The maximum number of HTTP requests to queue pending ability to execute.
      Default : 256

      integer (int32)

      analyticsHttpThreadCount
      optional

      The number of threads to service HTTP requests.
      Default : 16

      integer (int32)

      bindAddress
      optional

      The bind address to use.

      string

      bindToHost
      optional

      Bind to configured hostname instead of wildcard address.
      Default : false

      boolean

      clusterConnectRetries
      optional

      Number of attempts to contact CC before giving up.
      Default : 5

      integer (int32)

      collectDcpStateFromNodesTimeout
      optional

      The maximum time to wait to collect DCP state from all nodes in seconds.
      Default : 600

      integer (int32)

      compilerFramesize
      optional

      The page size (in bytes) for computation.
      Default : 32768

      integer (int32)

      compilerGroupmemory
      optional

      The memory budget (in bytes) for a group by operator instance in a partition.
      Default : 33554432

      integer (int32)

      compilerJoinmemory
      optional

      The memory budget (in bytes) for a join operator instance in a partition.
      Default : 33554432

      integer (int32)

      compilerParallelism
      optional

      The degree of parallelism for query execution. Zero means to use the storage parallelism as the query execution parallelism, while other integer values dictate the number of query execution parallel partitions. The system will fall back to use the number of all available CPU cores in the cluster as the degree of parallelism if the number set by a user is too large or too small.
      Default : 0

      integer (int32)

      compilerSortParallel
      optional

      Enables or disables full parallel sort.
      Default : false

      boolean

      compilerSortmemory
      optional

      The memory budget (in bytes) for a sort operator instance in a partition.
      Default : 33554432

      integer (int32)

      compilerWindowmemory
      optional

      The memory budget (in bytes) for a window operator instance in a partition.
      Default : 33554432

      integer (int32)

      coresMultiplier
      optional

      The factor to multiply by the number of cores to determine maximum query concurrent execution level.
      Default : 3

      integer (int32)

      dcpBufferAckWatermark
      optional

      The percentage of DCP connection buffer size at which to acknowledge bytes consumed to DCP producer.
      Default : 20
      Minimum value : 1
      Maximum value : 100

      integer (int32)

      dcpChannelReconnectRemoteIdleSeconds
      optional

      Reconnect remote DCP channels that are idle for the specified number of seconds to ensure permissions have not been lost. A value of 0 disables reconnects on idle.
      Default : 120

      integer (int32)

      dcpConnectionBufferSize
      optional

      DCP connection buffer size (in bytes).

      If the JVM maximum heap size is less than 8GB, the default for this parameter is 10 MB divided by the number of IO Devices on the node. Otherwise, the default is 1% of the JVM maximum heap size divided by the number of IO Devices on the node.

      integer (int32)

      deadlockWatchdogHaltDelaySeconds
      optional

      The delay (in seconds) to wait for graceful shutdown due to deadlocked threads, before halting.
      Default : 120

      integer (int32)

      deadlockWatchdogPollSeconds
      optional

      The frequency (in seconds) to scan for deadlocked threads.
      Default : 300

      integer (int32)

      jobHistorySize
      optional

      Limits the number of historical jobs remembered by the system to the specified value.
      Default : 10

      integer (int32)

      jobQueueCapacity
      optional

      The maximum number of jobs to queue before rejecting new jobs.
      Default : 4096

      integer (int32)

      jvmArgs
      optional

      JVM arguments to pass to the Analytics Driver. The default is undefined (null).

      Note that JVM arguments are generally not secure, and are exposed by cbcollect_info and the System Event log. To pass arguments opaquely, you may use Java command-line argument files.

      string

      logLevel
      optional

      The logging level.
      Default : "DEBUG"

      string

      maxWebRequestSize
      optional

      The maximum accepted web request size in bytes.
      Default : 52428800

      integer (int32)

      netBufferCount
      optional

      Number of network buffers per input/output channel.
      Default : 1

      integer (int32)

      netThreadCount
      optional

      Number of threads to use for Network I/O.
      Default : 1

      integer (int32)

      rebalancePullDatasetSizeFrequency
      optional

      The frequency at which the Analytics collection size is pulled from nodes during rebalance in seconds.
      Default : 5

      integer (int32)

      remoteLinkConnectTimeoutSeconds
      optional

      The maximum time (in seconds) to wait for a remote link connection to establish. A value of 0 disables timeout; a value of -1 sets timeout to the system default.
      Default : 60

      integer (int32)

      remoteLinkSocketTimeoutSeconds
      optional

      The maximum time (in seconds) to wait after establishing the connection for remote links; the maximum time of inactivity between two data packets. A value of 0 disables timeout; a value of -1 sets timeout to the system default.
      Default : 60

      integer (int32)

      requestsArchiveSize
      optional

      The maximum number of archived requests to maintain.
      Default : 50

      integer (int32)

      resultSweepThreshold
      optional

      The duration within which an instance of the result cleanup should be invoked in milliseconds.
      Default : 60000

      integer (int32)

      resultTtl
      optional

      Limits the amount of time results for asynchronous jobs should be retained by the system in milliseconds.
      Default : 86400000

      integer (int32)

      storageBuffercacheMaxopenfiles
      optional

      The maximum number of open files in the buffer cache.
      Default : 2147483647

      integer (int32)

      storageBuffercachePagesize
      optional

      The page size in bytes for pages in the buffer cache.
      Default : 131072

      integer (int32)

      storageCompressionBlock
      optional

      The default compression scheme for the storage.
      Default : "snappy"

      string

      storageMemorycomponentNumcomponents
      optional

      The number of memory components to be used per LSM index.
      Default : 2

      integer (int32)

      storageMemorycomponentPagesize
      optional

      The page size in bytes for pages allocated to memory components.
      Default : 131072

      integer (int32)

      storageWriteRateLimit
      optional

      The maximum disk write rate for each storage partition in bytes per second. Disabled if the provided value is less than or equal to 0.
      Default : 0

      integer (int64)

      threaddumpFrequencySeconds
      optional

      The frequency (in seconds) at which to log diagnostic thread dumps.
      Default : 300

      integer (int32)

      threaddumpLogLevel
      optional

      The log level at which to emit diagnostic thread dumps.
      Default : "DEBUG"

      string

      traceCategories
      optional

      Categories for tracing. The default is the empty array — no categories.

      < object > array

      txnDatasetCheckpointInterval
      optional

      The interval (in seconds) after which an Analytics collection is considered idle and persisted to disk.
      Default : 3600

      integer (int32)

      Node

      Name Description Schema

      jvmArgs
      optional

      JVM arguments to pass to the Analytics Driver. The default is undefined (null).

      Node-specific JVM arguments are appended to service-level JVM arguments. If the same JVM argument appears in both the service-level arguments and the node-specific arguments, the node-specific argument takes priority.

      Note that JVM arguments are generally not secure, and are exposed by cbcollect_info and the System Event log. To pass arguments opaquely, you may use Java command-line argument files.

      string

      storageBuffercacheSize
      optional

      The size of memory allocated to the disk buffer cache. The value should be a multiple of the buffer cache page size.

      The default is 1/4 of the allocated Analytics Service memory.

      integer

      storageMemorycomponentGlobalbudget
      optional

      The size of memory allocated to the memory components. The value should be a multiple of the memory component page size.

      The default is 1/4 of the allocated Analytics Service memory.

      integer

      Errors

      Name Description Schema

      error
      required

      An error message.

      string

      Security

      Analytics Manage

      The Analytics Configuration REST API supports HTTP basic authentication. Credentials can be passed via HTTP headers.

      Users must have one of the following RBAC roles:

      • Full Admin

      • Cluster Admin

      • Analytics Admin

      Refer to Roles for more details.

      Type : basic