CPP-710 - Add documentation for tracing (#214)

Author: mpenick

cpp-driver/include/cassandra.h

@@ -1982,7 +1982,7 @@ cass_cluster_set_max_schema_wait_time(CassCluster* cluster,
  * @param[in] max_wait_time_ms
  */
 CASS_EXPORT void
-cass_cluster_set_max_tracing_wait_time(CassCluster* cluster,
+cass_cluster_set_tracing_max_wait_time(CassCluster* cluster,
                                        unsigned max_wait_time_ms);
 
 /**
@@ -1995,7 +1995,7 @@ cass_cluster_set_max_tracing_wait_time(CassCluster* cluster,
  * @param[in] retry_wait_time_ms
  */
 CASS_EXPORT void
-cass_cluster_set_retry_tracing_wait_time(CassCluster* cluster,
+cass_cluster_set_tracing_retry_wait_time(CassCluster* cluster,
                                          unsigned retry_wait_time_ms);
 
 /**

cpp-driver/src/cluster_config.cpp

@@ -220,12 +220,12 @@ void cass_cluster_set_max_schema_wait_time(CassCluster* cluster,
   cluster->config().set_max_schema_wait_time_ms(wait_time_ms);
 }
 
-void cass_cluster_set_max_tracing_wait_time(CassCluster* cluster,
+void cass_cluster_set_tracing_max_wait_time(CassCluster* cluster,
                                            unsigned wait_time_ms) {
   cluster->config().set_max_tracing_wait_time_ms(wait_time_ms);
 }
 
-void cass_cluster_set_retry_tracing_wait_time(CassCluster* cluster,
+void cass_cluster_set_tracing_retry_wait_time(CassCluster* cluster,
                                            unsigned wait_time_ms) {
   cluster->config().set_retry_tracing_wait_time_ms(wait_time_ms);
 }

cpp-driver/topics/tracing/README.md

@@ -0,0 +1,76 @@
+# Tracing
+
+Tracing can be used to troubleshoot query performance problems and can be
+enabled per request. When enabled, it provides detailed request information
+related to internal, server-side operations. Those operations are stored in
+tables under the `system_traces` keyspace.
+
+## Enabling
+
+Tracing can be enabled per request for both statements (`CassStatement`) and
+batches (`CassBatch`).
+
+### Enable Tracing on a Statement (`CassStatement`)
+
+```c
+const char* query = "SELECT * FROM keyspace1.table1";
+CassStatement* statement = cass_statement_new(query, 0);
+
+/* Enable tracing on the statement */
+cass_statement_set_tracing(statement, cass_true)
+
+/* ... */
+```
+
+### Enable Tracing on a Batch (`CassBatch`)
+
+```
+CassBatch* batch = cass_batch_new(CASS_BATCH_TYPE_UNLOGGED);
+
+/* Enable tracing on the batch */
+cass_batch_set_tracing(batch, cass_true)
+
+/* ... */
+```
+
+## Tracing Identifier
+
+When tracing is enabled, a request's future (`CassFuture`) will provide a unique
+tracing identifier. This tracing identifier can be used by an application to
+query tables in the `system_traces` keyspace.
+
+```c
+CassUuid tracing_id;
+if (cass_future_tracing_id(future, &tracing_id) == CASS_OK) {
+  /* Use `tracing_id` to query tables in the `system_trace` keyspace */
+} else {
+  /* Handle error. If this happens then either a request error occurred or the
+   * request type for the future does not support tracing.
+   */
+}
+```
+
+**Note**: The driver does not return the actual tracing data for the request. The
+application itself must use the returned tracing identifier to query the tables.
+
+## Configuration
+
+By default, when tracing is enabled, the driver will wait for the query's tracing
+data to become available in the server-side tables before setting the request's
+future. The amount of time it will wait, retry, and the consistency level of the
+tracing data can be controls by setting `CassCluster` configuration options.
+
+```c
+CassCluster* cluster = cass_cluster_new();
+
+/* Wait a maximum of 15 milliseconds for tracing data to become available */
+cass_cluster_set_tracing_max_wait_time(cluster, 15);
+
+/* Wait 3 milliseconds before rechecking for the tracing data */
+cass_cluster_set_tracing_retry_wait_time(cluster, 3);
+
+/* Check the tracing data tables using consistency level ONE */
+cass_cluster_set_tracing_consistency(cluster, CASS_CONSISTENCY_ONE);
+
+/* ... */
+```