Client Settings for the .NET SDK

The ClusterOptions class enables you to configure .NET SDK options for bootstrapping, timeouts, reliability, and performance. You can configure the client programmatically using JSON config files, Environmental variables settings, XML based configuration such has app.config or web.config files.

Configuration Basics

Configuration is essentially the same as SDK 2.x retaining capabilites with less tunable properties. Instead of using a ClientConfiguration object, you would use a ClusterOptions object. For example, to use a custom timeout for Key/Value (K/V) operations you would do something like this:

// SDK 3.0 custom k/v timeout
var options = new ClusterOptions
{
    KvTimeout = TimeSpan.FromMilliseconds(5)
};

Fluent Configuration

you can also build the Cluster Options in a fluent way for example

var options = new ClusterOptions()
  .WithConnectionString("couchbase://localhost")
  .WithCredentials(username: "user", password: "password")
  .WithBuckets("travel-sample")
  .WithLogging(LoggerFactory.Create(builder =>
  {
      builder.AddFilter("Couchbase", LogLevel.Debug)
      .AddEventLog();
  }));

The cluster options are passed into the Cluster object via a constructor:

var cluster = new Cluster("couchbase://localhost", options);

Or by using one of the static Cluster.Connect(…) methods:

var cluster = Cluster.Connect("couchbase://localhost", options);

JSON Configuration

In support of .NET Core, the client can now be configured using JSON config files.

JSON configuration is only supported for versions of the SDK 2.3.0 and greater running on .NET Core 1.0 or greater.

Below is an example of how appsettings.json can be coded for cluster options, note the key ClusterOptions is simply a name of an object and can be anything you may want it to be.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "ClusterOptions": {
    "ConnectionString": "couchbase://localhost",
    "UserName": "user",
    "Password": "password",
    "BucketName" : "travel-sample"
  }
}

Here is an example of building the options from the JSON configuration above:

var settings = Configuration.GetSection("ClusterOptions");
services.Configure<ClusterOptions>(settings);

The options can now be made accessible through any services as below,

public CustomService ( IOptions<ClusterOptions> clusterOptions)
{
    var bucketName = clusterOptions.BucketName;
}

The "travel-sample" bucket is opened using any of the overridden defaults.

Configuration Options

The following tables cover all possible configuration options and explain their usage and default values. The tables categorize the options into groups for bootstrapping, timeout, reliability, performance, and advanced options.

Security Options

By default the client will connect to Couchbase Server using an unencrypted connection. If you are using the Enterprise Edition, it’s possible to secure the connection using TLS.

Template for configuring security settings

var options = new ClusterOptions()
{
    EnableTls = true
};

Unless you set EnableTls to true, none of the other security settings in this section have any effect.

Name: Enabling Secure Connections: Cluster Option: EnableTls(boolean)

Default: false

Set this to true to encrypt all communication between the client and server using TLS. This feature requires the Enterprise Edition of Couchbase Server 3.0 or later. If TLS is enabled you must also specify the trusted certificates by calling exactly one of trustCertificate, trustCertificates, or trustManagerFactory. Please see the Managing Connections section for more details on how to set it up properly.
Name: Enable Certificate Based Authentication: Cluster Option: EnableCertificateAuthentication(boolean)

EnableCertificateAuthentication is required to be set to true to use Certificate Authentication
Name: Ignore Remote Certificate Name Mismatch: Cluster Option: IgnoreRemoteCertificateNameMismatch(boolean)

Default: false

If TLS is enabled via EnableTls, setting this to true will disable hostname validation when authenticating connections to Couchbase Server. This is typically done in test or development environments where a domain name (FQDN) has not been specified for the bootstrap server’s URI, and the IP address is use to validate the certificate, which will fail with a RemoteCertificateNameMismatch error.
Name: Enable Certificate Revocation: Cluster Option: EnableCertificateRevocation(boolean)

Default: false

A Boolean value that specifies whether the certificate revocation list is checked during authentication.

I/O Options

This section provides basic settings that will come in handy while configuring network related operations.

Template for configuring I/O settings

var options = new ClusterOptions()
{
    EnableDnsSrvResolution = true
};

Name: DNS SRV Enabled

Cluster Option: EnableDnsSrvResolution(boolean)

Default: true

Gets the bootstrap node list from a DNS SRV record. See the Connection Management section for more information on how to use it properly.

Name: Mutation Tokens Enabled

Cluster Options: EnableMutationTokens(boolean)

Default: true

Mutation tokens allow enhanced durability requirements as well as advanced N1QL querying capabilities. Set this to false if you do not require these features and wish to avoid the associated overhead.

Name: Socket Keepalive

Cluster Option: EnableTcpKeepAlives(boolean)

Default: true

If enabled, the client periodically sends a TCP keepalive to the server to prevent firewalls and other network equipment from dropping idle TCP connections.

Name: Socket Keepalive Interval

Cluster Option: TcpKeepAliveTime(TimeSpan)

Default: 60s

The idle time after which a TCP keepalive gets fired. (This setting has no effect if EnableTcpKeepAlives is false.)

This setting only propagates to the OS on Linux when the epoll transport is used. On all other platforms, the OS-configured time is used (and you need to tune it there if you want to override the default interval).

Name: Key/Value Endpoints per Node

Cluster Option: NumKvConnections(int)

Default: 1

The number of actual endpoints (sockets) to open per node in the cluster against the Key/Value service. By default, for every node in the cluster one socket is opened where all traffic is pushed through. That way the SDK implicitly benefits from network batching characteristics when the workload increases. If you suspect based on profiling and benchmarking that the socket is saturated you can think about slightly increasing it to have more "parallel pipelines". This might be especially helpful if you need to push large documents through it. The recommendation is keeping it at 1 unless there is other evidence.

Durable Write operations with Couchbase Server 6.5 and above require up to 16 kvEndpoints per node, for most efficient operation, unless the environment dictates something a little lower.

Name: Max HTTP Endpoints per Service per Node

Cluster Option: MaxHttpConnections(int)

Default: 0

Each service (except the Key/Value service) has a separate dynamically sized pool of HTTP connections for issuing requests. This setting puts an upper bound on the number of HTTP connections in each pool.

Name: Enable Config Poll: Cluster Option: EnableConfigPolling(boolean)

Default: true

Enables Configuration heartbeat checks.

Name: Config Poll Interval: Cluster Option: ConfigPollInterval(TimeSpan)

Default: 2.5s

The interval at which the client fetches cluster topology information in order to proactively detect changes. EnableConfigPolling should be set to true to leverage this setting.

Circuit Breaker Options

Circuit breakers are a tool for preventing cascading failures.

When a circuit is closed, requests are sent to the server as normal. If too many requests fail within a certain time window, the breaker opens the circuit, preventing requests from going through.

When a circuit is open, any requests to the service immediately fail without the client even talking to the server. After a "sleep delay" elapses, the next request is allowed to go through the to the server. This trial request is called a "canary."

Each service has an associated circuit breaker which may be configured independently of the others. The IoConfig builder has methods for configuring the circuit breakers of each service.

Template for configuring circuit breaker settings

var options = new ClusterOptions()
{
    CircuitBreakerConfiguration =
    new Couchbase.Core.CircuitBreakers.CircuitBreakerConfiguration
    {
        Enabled = true,
        VolumeThreshold = 45,
        ErrorThresholdPercentage = 25,
        SleepWindow = TimeSpan.FromSeconds(1),
        RollingWindow = TimeSpan.FromMinutes(2)

    }
}

The properties of a circuit breaker are described below.

Enabled: Default: true

Enables or disables this circuit breaker.

If this property is set to false, then the circuit breaker is not used and all other properties are ignored.
VolumeThreshold: Default: 20

The volume threshold defines how many operations must be in the window before the threshold percentage can be meaningfully calculated.
ErrorThresholdPercentage: Default: 50

The percentage of operations in a window that may fail before the circuit is opened. The value is an integer in the range [0,100].
SleepWindow: Default: 5s

The delay between when the circuit opens and when the canary is tried.
RollingWindow: Default: 1m

How long the window is in which the number of failed ops are tracked in a rolling fashion.

Timeout Options

The default timeout values are suitable for most environments, and should be adjusted only after profiling the expected latencies in your deployment environment. If you get a timeout exception, it may be a symptom of another issue; increasing the timeout duration is sometimes not the best long-term solution.

Most timeouts can be overridden on a per-operation basis (for example, by passing a custom options block to a "get" or "query" method). The values set here are used as the defaults when no per-operation timeout is specified.

Template for configuring timeouts

 var options = new ClusterOptions()
{
    KvTimeout = TimeSpan.FromSeconds(2.5),
    KvDurabilityTimeout = TimeSpan.FromSeconds(10),
    ViewTimeout = TimeSpan.FromSeconds(75),
    QueryTimeout = TimeSpan.FromSeconds(75),
    SearchTimeout = TimeSpan.FromSeconds(75),
    AnalyticsTimeout = TimeSpan.FromSeconds(75),
    ManagementTimeout = TimeSpan.FromSeconds(75)
};

Timeout Options Reference

Name: Key-Value Timeout

Cluster Option: KvTimeout(TimeSpan)

Default: 2.5s — but see TIP, below

The Key/Value default timeout is used on operations which are performed on a specific key if not overridden by a custom timeout. This includes all commands like Get(), GetFromReplica() and all mutation commands, but does not include operations that are performed with enhanced durability requirements.

Durable Write operations have their own timeout setting, KvDurableTimeout, see below.

Name: Key-Value Durable Operation Timeout

Cluster Option: KvDurableTimeout(TimeSpan)

Default: 10s

Key/Value operations with enhanced durability requirements may take longer to complete, so they have a separate default timeout.

The KvDurableTimeout property is not part of the stable API and may change or be removed at any time.

Name: View Timeout

Cluster Option: ViewTimeout(TimeSpan)

Default: 75s

The View timeout is used on view operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows. Also, if there is a node failure during the request the internal cluster timeout is set to 60 seconds.

Name: Query Timeout

Cluster Option: QueryTimeout(TimeSpan)

Default: 75s

The Query timeout is used on all N1QL query operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.

Name: Search Timeout

Cluster Option: SearchTimeout(TimeSpan)

Default: 75s

The Search timeout is used on all FTS operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.

Name: Analytics Timeout

Cluster Option: AnalyticsTimeout(TimeSpan)

Default: 75s

The Analytics timeout is used on all Analytics query operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.

Name: Management Timeout

Cluster Option: ManagementTimeout(TimeSpan)

Default: 75s

The management timeout is used on all cluster management APIs (BucketManager, UserManager, CollectionManager, QueryIndexManager, etc.) if not overridden by a custom timeout. The default is quite high because some operations (such as flushing a bucket, for example) might take a long time.

General Options

Name: Unordered Execution

Cluster Option: UnorderedExecutionEnabled

Default: true

From Couchbase 7.0, Out-of-Order execution allows the server to concurrently handle multiple requests on the same connection, potentially improving performance for durable writes and multi-document ACID transactions. This means that tuning the number of connections (KV endpoints) is no longer necessary as a workaround where data not available in the cache is causing timeouts.

This is set to true by default. Note, changing the setting will only affect Server versions 7.0 onwards.

Name: Transcoder

Cluster Option: Transcoder(Transcoder)

Default: JsonTranscoder

The transcoder is responsible for converting KV binary packages to and from C# objects.

The default transcoder assumes you are working with JSON documents. It uses the configured jsonSerializer to convert between JSON and C# objects. When writing documents it sets the appropriate flags to indicate the document content is JSON.

The transcoder configured here is just the default; it can be overridden on a per-operation basis.

Name: Threshold Tracer

Cluster Option: WithThresholdTracing(ThresholdOptions)

Default: ThresholdLoggingTracer

The default tracer logs the slowest requests per service.

var clusterOptions = new ClusterOptions();
  clusterOptions.WithThresholdTracing(thresholdOptions =>
  {
      thresholdOptions.WithEmitInterval(TimeSpan.FromSeconds(10));
      thresholdOptions.WithSampleSize(10);
      thresholdOptions.WithKvThreshold(TimeSpan.FromMilliseconds(500));
      thresholdOptions.WithQueryThreshold(TimeSpan.FromSeconds(1));
      thresholdOptions.WithSearchThreshold(TimeSpan.FromSeconds(1));
      thresholdOptions.WithViewThreshold(TimeSpan.FromSeconds(1));
      thresholdOptions.WithAnalyticsThreshold(TimeSpan.FromSeconds(1));
  });

Name: Orphaned Response Tracer

Cluster Option: WithOrphanTracing(OrphanOptions)

Default: enabled

Orphaned Response Logger will log orphaned responses if a request fails to complete for some reason.

var clusterOptions = new ClusterOptions();
  clusterOptions.WithOrphanTracing(orphanOptions =>
  {
    orphanOptions.WithEnabled(true);
    orphanOptions.WithEmitInterval(TimeSpan.FromSeconds(10));
    orphanOptions.WithSampleSize(10);
  });

Commonly Used Options

The defaults above have been carefully considered and in general it is not recommended to make changes without expert guidance or careful testing of the change. Some options may be commonly used together in certain envionments or to achieve certain effects.

Constrained Network Environments

Though wide area network (WAN) connections are not directly supported, some development and non-critical operations activities across a WAN are convenient. Most likely for connecting to Couchbase Capella, or Server running in your own cloud account, whilst developing from a laptop or other machine not located in the same data center. These settings are some you may want to consider adjusting:

Connect Timeout to 30s
Key-Value Timeout to 5s
Config Poll Interval to 10s
Circuit Breaker ErrorThresholdPercentage to 75

A program using the SDK can also use the waitUntilReady() API call to handle all connection negotiations and related errors at one place. It may be useful to block in, for example, a basic console testing application for up to 30 seconds before proceeding in the program to perform data operations. See the API reference for further details.