PYCBC-486: Document Threshold Logger settings

Change-Id: I559f280b71559b7f69fdd954806e778a6050d486
Reviewed-on: http://review.couchbase.org/94358
Tested-by: Build Bot <[email protected]>
Reviewed-by: Ellis Breen <[email protected]>

couchbase/bucket.py

@@ -125,6 +125,7 @@ def newfn(self, key, *args, **kwargs):
 
 
 class Bucket(_Base):
+
     def __init__(self, *args, **kwargs):
         """Connect to a bucket.
 
@@ -1772,17 +1773,169 @@ def redaction(self):
     def redaction(self, val):
         return self._cntl(_LCB.LCB_CNTL_LOG_REDACTION, value=val, value_type='int')
 
-    def __getattribute__(self, name):
-        if name in _LCB.TRACING.keys():
-            return self._cntl(**_LCB.TRACING[name])
-        else:
-            return super(Bucket, self).__getattribute__(name)
+    @property
+    def tracing_orphaned_queue_flush_interval(self):
+        """
+        The tracing orphaned queue flush interval, in fractions of a second.
 
-    def __setattr__(self, name, value):
-        if name in _LCB.TRACING.keys():
-            return self._cntl(value=value, **_LCB.TRACING[name])
-        else:
-            super(Bucket, self).__setattr__(name, value)
+        ::
+            # Set tracing orphaned queue flush interval to 0.5 seconds
+            cb.tracing_orphaned_queue_flush_interval = 0.5
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL, value_type="timeout")
+
+    @tracing_orphaned_queue_flush_interval.setter
+    def tracing_orphaned_queue_flush_interval(self, val):
+        return self._cntl(op=_LCB.TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL, value=val, value_type="timeout")
+
+    @property
+    def tracing_orphaned_queue_size(self):
+        """
+        The tracing orphaned queue size.
+
+        ::
+            # Set tracing orphaned queue size to 100 entries
+            cb.tracing_orphaned_queue_size = 100
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_ORPHANED_QUEUE_SIZE, value_type="uint32_t")
+
+    @tracing_orphaned_queue_size.setter
+    def tracing_orphaned_queue_size(self, val):
+        return self._cntl(op=_LCB.TRACING_ORPHANED_QUEUE_SIZE, value=val, value_type="uint32_t")
+
+    @property
+    def tracing_threshold_queue_flush_interval(self):
+        """
+        The tracing threshold queue flush interval, in fractions of a second.
+
+        ::
+            # Set tracing threshold queue flush interval to 0.5 seconds
+            cb.tracing_threshold_queue_flush_interval = 0.5
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL, value_type="timeout")
+
+    @tracing_threshold_queue_flush_interval.setter
+    def tracing_threshold_queue_flush_interval(self, val):
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL, value=val, value_type="timeout")
+
+    @property
+    def tracing_threshold_queue_size(self):
+        """
+        The tracing threshold queue size.
+
+        ::
+            # Set tracing threshold queue size to 100 entries
+            cb.tracing_threshold_queue_size = 100
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_QUEUE_SIZE, value_type="uint32_t")
+
+    @tracing_threshold_queue_size.setter
+    def tracing_threshold_queue_size(self, val):
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_QUEUE_SIZE, value=val, value_type="uint32_t")
+
+    @property
+    def tracing_threshold_kv(self):
+        """
+        The tracing threshold for KV, in fractions of a second.
+
+        ::
+            # Set tracing threshold for KV to 0.5 seconds
+            cb.tracing_threshold_kv = 0.5
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_KV, value_type="timeout")
+
+    @tracing_threshold_kv.setter
+    def tracing_threshold_kv(self, val):
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_KV, value=val, value_type="timeout")
+
+    @property
+    def tracing_threshold_n1ql(self):
+        """
+        The tracing threshold for N1QL, in fractions of a second.
+
+        ::
+            # Set tracing threshold for N1QL to 0.5 seconds
+            cb.tracing_threshold_n1ql = 0.5
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_N1QL, value_type="timeout")
+
+    @tracing_threshold_n1ql.setter
+    def tracing_threshold_n1ql(self, val):
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_N1QL, value=val, value_type="timeout")
+
+    @property
+    def tracing_threshold_view(self):
+        """
+        The tracing threshold for View, in fractions of a second.
+
+        ::
+            # Set tracing threshold for View to 0.5 seconds
+            cb.tracing_threshold_view = 0.5
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_VIEW, value_type="timeout")
+
+    @tracing_threshold_view.setter
+    def tracing_threshold_view(self, val):
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_VIEW, value=val, value_type="timeout")
+
+    @property
+    def tracing_threshold_fts(self):
+        """
+        The tracing threshold for FTS, in fractions of a second.
+
+        ::
+            # Set tracing threshold for FTS to 0.5 seconds
+            cb.tracing_threshold_fts = 0.5
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_FTS, value_type="timeout")
+
+    @tracing_threshold_fts.setter
+    def tracing_threshold_fts(self, val):
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_FTS, value=val, value_type="timeout")
+
+    @property
+    def tracing_threshold_analytics(self):
+        """
+        The tracing threshold for analytics, in fractions of a second.
+
+        ::
+            # Set tracing threshold for analytics to 0.5 seconds
+            cb.tracing_threshold_analytics = 0.5
+
+        """
+
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_ANALYTICS, value_type="timeout")
+
+    @tracing_threshold_analytics.setter
+    def tracing_threshold_analytics(self, val):
+        return self._cntl(op=_LCB.TRACING_THRESHOLD_ANALYTICS, value=val, value_type="timeout")
+
+    # Backward compatibility aliases, to be removed by next major revision
+    TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL = tracing_orphaned_queue_flush_interval
+    TRACING_ORPHANED_QUEUE_SIZE = tracing_orphaned_queue_size
+    TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL = tracing_threshold_queue_flush_interval
+    TRACING_THRESHOLD_QUEUE_SIZE = tracing_threshold_queue_size
+    TRACING_THRESHOLD_KV = tracing_threshold_kv
+    TRACING_THRESHOLD_N1QL = tracing_threshold_n1ql
+    TRACING_THRESHOLD_VIEW = tracing_threshold_view
+    TRACING_THRESHOLD_FTS = tracing_threshold_fts
+    TRACING_THRESHOLD_ANALYTICS = tracing_threshold_analytics
 
     def _cntl(self, *args, **kwargs):
         """Low-level interface to the underlying C library's settings. via

setup.py

@@ -30,11 +30,9 @@
 extoptions['extra_compile_args'] = []
 extoptions['extra_link_args'] = []
 
-if os.environ.get('PYCBC_TRACING_ENABLE'):
-    extoptions['extra_compile_args'] += ['-DPYCBC_TRACING_ENABLE']
-if os.environ.get('PYCBC_DEBUG'):
-    extoptions['extra_compile_args'] += ['-DPYCBC_DEBUG']
-
+comp_flags = ["PYCBC_TRACING_ENABLE","PYCBC_DEBUG","PYCBC_CRYPTO_VERSION"]
+extoptions['extra_compile_args'] += ["-D{}={}".format(flag,os.environ.get(flag))
+                                     for flag in comp_flags if flag in os.environ.keys()]
 if sys.platform != 'win32':
     extoptions['libraries'] = ['couchbase']
     if os.environ.get('PYCBC_DEBUG'):

src/bucket.c

@@ -224,6 +224,7 @@ Bucket_decrypt_fields(pycbc_Bucket *self, PyObject *args)
         cmd.nfields = pycbc_populate_fieldspec(&cmd.fields, fieldspec);
         res = lcbcrypto_decrypt_fields(self->instance, &cmd);
 #else
+        (void)fieldspec;
         res = lcbcrypto_decrypt_document(self->instance, &cmd);
 #endif
     }

src/constants.c

@@ -234,28 +234,75 @@ static void setup_tracing_map(PyObject *module,
     X(TRACING_THRESHOLD_N1QL, convert_timevalue) DIV\
     X(TRACING_THRESHOLD_VIEW, convert_timevalue) DIV\
     X(TRACING_THRESHOLD_FTS, convert_timevalue) DIV\
-    X(TRACING_THRESHOLD_ANALYTICS, convert_timevalue) DIV \
-    X(ENABLE_TRACING, convert_intbool)
+    X(TRACING_THRESHOLD_ANALYTICS, convert_timevalue)
+
     PyObject* convert_timevalue = pycbc_SimpleStringZ("timeout");
+#define convert_timevalue_desc "The %S, in fractions of a second."
+#define convert_timevalue_desc_val "0.5"
+#define convert_timevalue_desc_val_units " seconds"
     PyObject* convert_u32 = pycbc_SimpleStringZ("uint32_t");
+#define convert_u32_desc "The %S."
+#define convert_u32_desc_val "100"
+#define convert_u32_desc_val_units " entries"
     PyObject* convert_intbool = pycbc_SimpleStringZ("int");
+#define convert_intbool_desc "Whether %S is set. "
+#define convert_intbool_desc_val "True"
+#define convert_intbool_desc_val_units ""
     PyObject *result = PyDict_New();
     LCB_FOR_EACH_THRESHOLD_PARAM(LCB_CNTL_CONSTANT, ;);
     LCB_CNTL_TRACING_THRESHOLD_KV;
-#define X(NAME, VALUE)                                       \
-    {                                                        \
-        PyObject *attrdict = PyDict_New();                   \
-        PyObject *val = PyLong_FromLong(LCB_CNTL_##NAME);    \
-        PyDict_SetItemString(attrdict, "op", val);           \
-        PyDict_SetItemString(attrdict, "value_type", VALUE); \
-        PyDict_SetItemString(result, #NAME, attrdict);       \
-        Py_DecRef(val);                                      \
-        Py_DecRef(attrdict);                                 \
+#define X(NAME, TYPE)                                       \
+    {                                                       \
+        PyObject *attrdict = PyDict_New();                  \
+        PyObject *val = PyLong_FromLong(LCB_CNTL_##NAME);   \
+        PyDict_SetItemString(attrdict, "op", val);          \
+        PyDict_SetItemString(attrdict, "value_type", TYPE); \
+        PyDict_SetItemString(result, #NAME, attrdict);      \
+        Py_DecRef(val);                                     \
+        Py_DecRef(attrdict);                                \
     }
     LCB_FOR_EACH_THRESHOLD_PARAM(X, ;);
+#undef X
+
+#define X(NAME,TYPE)\
+    {\
+        PyObject* as_string = pycbc_SimpleStringZ(#NAME);\
+        PyObject* as_lower_case = PyObject_CallMethod(as_string, "lower","");\
+        PyObject* as_words = PyObject_CallMethod(as_lower_case, "replace", "ss", "_", " ");\
+        pycbc_replace_str(&as_words, "analytics", "for analytics");\
+        pycbc_replace_str(&as_words, "n1ql", "for N1QL");\
+        pycbc_replace_str(&as_words, "kv", "for KV");\
+        pycbc_replace_str(&as_words, "fts", "for FTS");\
+        pycbc_replace_str(&as_words, "view", "for View");\
+        pycbc_print_pyformat(\
+        "@property\n"\
+        "def %S(self):\n"\
+        "    \"\"\"\n"\
+        "    " TYPE##_desc "\n"\
+        "\n"\
+        "    ::\n"\
+        "        # Set %S to " TYPE##_desc_val TYPE##_desc_val_units "\n"\
+        "        cb.%S=" TYPE##_desc_val "\n" \
+        "\n"\
+        "    \"\"\"\n"\
+        "    \n"\
+        "    return self._cntl(op=_LCB." #NAME ", value_type=\"%S\")\n\n", as_lower_case, as_words, as_words, as_lower_case, TYPE  );\
+        pycbc_print_pyformat(\
+        "@%S.setter\n"\
+        "def %S(self, val):\n"\
+        "    return self._cntl(op=_LCB." #NAME ", value=val, value_type=\"%S\")\n\n", as_lower_case, as_lower_case, TYPE);\
+        Py_DecRef(as_words);\
+        Py_DecRef(as_lower_case);\
+        Py_DecRef(as_string);\
+    }
+
+#ifdef PYCBC_GEN_PYTHON
+LCB_FOR_EACH_THRESHOLD_PARAM(X, ; );
+#endif
 #undef X
     Py_DecRef(convert_timevalue);
     Py_DecRef(convert_u32);
+    Py_DecRef(convert_intbool);
     PyModule_AddObject(module, "TRACING", result);
 #undef LCB_FOR_EACH_THRESHOLD_PARAM
 }

src/ext.c

@@ -495,8 +495,9 @@ void pycbc_exception_log(const char* file, int line, int clear)
         }
     }
 }
+#endif
 
-void pycbc_log_pyformat(const char *file, int line, const char *format, ...)
+void pycbc_print_pyformat(const char *format, ...)
 {
     va_list v1;
     PyObject *type = NULL, *value = NULL, *traceback = NULL;
@@ -508,8 +509,7 @@ void pycbc_log_pyformat(const char *file, int line, const char *format, ...)
     if (!formatted || PyErr_Occurred()) {
         PYCBC_EXCEPTION_LOG
     } else {
-        PYCBC_DEBUG_LOG_WITH_FILE_AND_LINE_NEWLINE(
-                file, line, "%s", PYCBC_CSTR(formatted));
+        fprintf(stderr, "%s", PYCBC_CSTR(formatted));
     }
     Py_XDECREF(formatted);
     PyErr_Print();
@@ -518,7 +518,13 @@ void pycbc_log_pyformat(const char *file, int line, const char *format, ...)
     }
 }
 
-#endif
+PyObject* pycbc_replace_str(PyObject** string, const char* pat, const char* replace)
+{
+    PyObject* result = PyObject_CallMethod(*string, "replace", "ss", pat, replace);
+    Py_DecRef(*string);
+    *string = result;
+    return result;
+}
 
 #ifdef PYCBC_TRACING
 pycbc_stack_context_handle pycbc_Context_deref_debug(

src/pycbc.h

@@ -20,12 +20,15 @@
  * @author Mark Nunberg
  */
 
+
 #ifdef PYCBC_DEBUG
-#define PYCBC_DEBUG_LOG_RAW(...) printf(__VA_ARGS__);
-void pycbc_log_pyformat(const char *file, int line, const char *format, ...);
+#define PYCBC_DEBUG_LOG_RAW(...) fprintf(stderr,__VA_ARGS__);
+void pycbc_print_pyformat(const char *format, ...);
 void pycbc_exception_log(const char *file, int line, int clear);
 #define PYCBC_DEBUG_PYFORMAT(FORMAT, ...) \
-    pycbc_log_pyformat(__FILE__, __LINE__, FORMAT, __VA_ARGS__, NULL)
+    PYCBC_DEBUG_LOG_PREFIX(__FILE__, __LINE__)\
+    pycbc_print_pyformat(FORMAT, __VA_ARGS__, NULL);\
+    fprintf(stderr, "\n");
 #define PYCBC_EXCEPTION_LOG_NOCLEAR pycbc_exception_log(__FILE__, __LINE__, 0);
 #define PYCBC_EXCEPTION_LOG pycbc_exception_log(__FILE__, __LINE__, 1);
 #else
@@ -35,8 +38,9 @@ void pycbc_exception_log(const char *file, int line, int clear);
 #define PYCBC_EXCEPTION_LOG PyErr_Clear();
 #endif
 
+#define PYCBC_DEBUG_LOG_PREFIX(FILE,LINE) PYCBC_DEBUG_LOG_RAW("at %s line %d:", FILE, LINE)
 #define PYCBC_DEBUG_LOG_WITH_FILE_AND_LINE_POSTFIX(FILE,LINE,POSTFIX,...)\
-    PYCBC_DEBUG_LOG_RAW("at %s line %d:", FILE, LINE)\
+    PYCBC_DEBUG_LOG_PREFIX(FILE,LINE)\
     PYCBC_DEBUG_LOG_RAW(__VA_ARGS__)\
     PYCBC_DEBUG_LOG_RAW(POSTFIX)
 #define PYCBC_DEBUG_LOG_WITH_FILE_AND_LINE_NEWLINE(FILE,LINE,...) PYCBC_DEBUG_LOG_WITH_FILE_AND_LINE_POSTFIX(FILE,LINE,"\n", __VA_ARGS__)
@@ -201,6 +205,8 @@ unsigned long pycbc_IntAsUL(PyObject *o);
 
 #endif
 
+PyObject* pycbc_replace_str(PyObject** string, const char* pat, const char* replace);
+
 /**
  * Fetches a valid TTL from the object
  * @param obj an object to be parsed as the TTL