traceview 3.0.0-java

data/ext/oboe_metal/extconf.rb

@@ -0,0 +1,61 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+require 'mkmf'
+require 'rbconfig'
+
+# Check if we're running in JRuby
+jruby = defined?(JRUBY_VERSION) ? true : false
+
+openshift = ENV.key?('OPENSHIFT_TRACEVIEW_DIR')
+
+# When on OpenShift, set the mkmf lib paths so we have no issues linking to
+# the TraceView libs.
+if openshift
+  tv_lib64 = "#{ENV['OPENSHIFT_TRACEVIEW_DIR']}usr/lib64"
+  tv_tlyzer = "#{ENV['OPENSHIFT_TRACEVIEW_DIR']}usr/lib64/tracelyzer"
+
+  idefault = "#{ENV['OPENSHIFT_TRACEVIEW_DIR']}usr/include"
+  ldefault = "#{tv_lib64}:#{tv_tlyzer}"
+
+  dir_config('oboe', idefault, ldefault)
+else
+  dir_config('oboe')
+end
+
+if jruby || ENV.key?('TRACEVIEW_URL')
+  # Build the noop extension under JRuby and Heroku.
+  # The oboe-heroku gem builds it's own c extension which links to
+  # libs specific to a Heroku dyno
+  # FIXME: For JRuby we need to remove the c extension entirely
+  create_makefile('oboe_noop', 'noop')
+
+elsif have_library('oboe', 'oboe_config_get_revision', 'oboe/oboe.h')
+
+  $libs = append_library($libs, 'oboe')
+  $libs = append_library($libs, 'stdc++')
+
+  $CFLAGS << " #{ENV['CFLAGS']}"
+  $CPPFLAGS << " #{ENV['CPPFLAGS']}"
+  $LIBS << " #{ENV['LIBS']}"
+
+  # On OpenShift user rpath to point out the TraceView libraries
+  if openshift
+    $LDFLAGS << " #{ENV['LDFLAGS']} -Wl,-rpath=#{tv_lib64},--rpath=#{tv_tlyzer}"
+  end
+
+  if RUBY_VERSION < '1.9'
+    cpp_command('g++')
+    $CPPFLAGS << '-I./src/'
+  end
+  create_makefile('oboe_metal', 'src')
+
+else
+  if have_library('oboe')
+    $stderr.puts 'Error: The oboe gem requires an updated liboboe.  Please update your liboboe packages.'
+  end
+
+  $stderr.puts 'Error: Could not find the base liboboe libraries.  No tracing will occur.'
+  create_makefile('oboe_noop', 'noop')
+end
+

data/ext/oboe_metal/noop/noop.c

@@ -0,0 +1,7 @@
+#include <ruby.h>
+
+/* ruby calls this to load the extension */
+void Init_oboe_noop(void) {
+  /* assume we haven't yet defined Hola */
+  VALUE klass = rb_define_class("OboeNoop", rb_cObject);
+}

data/ext/oboe_metal/src/bson/bson.h

@@ -0,0 +1,221 @@
+/* bson.h */
+
+/*    Copyright 2009, 2010 10gen Inc.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#ifndef _BSON_H_
+#define _BSON_H_
+
+#define MONGO_HAVE_STDINT
+#include "platform_hacks.h"
+#include <time.h>
+
+MONGO_EXTERN_C_START
+
+typedef enum {
+    bson_error=-1,
+    bson_eoo=0,
+    bson_double=1,
+    bson_string=2,
+    bson_object=3,
+    bson_array=4,
+    bson_bindata=5,
+    bson_undefined=6,
+    bson_oid=7,
+    bson_bool=8,
+    bson_date=9,
+    bson_null=10,
+    bson_regex=11,
+    bson_dbref=12, /* deprecated */
+    bson_code=13,
+    bson_symbol=14,
+    bson_codewscope=15,
+    bson_int = 16,
+    bson_timestamp = 17,
+    bson_long = 18
+} bson_type;
+
+typedef int bson_bool_t;
+
+typedef struct {
+    char * data;
+    bson_bool_t owned;
+} bson;
+
+typedef struct {
+    const char * cur;
+    bson_bool_t first;
+} bson_iterator;
+
+typedef struct {
+    char * buf;
+    char * cur;
+    int bufSize;
+    bson_bool_t finished;
+    int stack[32];
+    int stackPos;
+} bson_buffer;
+
+#pragma pack(1)
+typedef union{
+    char bytes[12];
+    int ints[3];
+} bson_oid_t;
+#pragma pack()
+
+typedef int64_t bson_date_t; /* milliseconds since epoch UTC */
+
+/* ----------------------------
+   READING
+   ------------------------------ */
+
+
+bson * bson_empty(bson * obj); /* returns pointer to static empty bson object */
+int bson_copy(bson* out, const bson* in); /* puts data in new buffer. NOOP if out==NULL */
+bson * bson_from_buffer(bson * b, bson_buffer * buf);
+bson * bson_init( bson * b , char * data , bson_bool_t mine );
+bson * bson_init_safe( bson * b , char * data , bson_bool_t mine , size_t buflen);
+int bson_size(const bson * b );
+void bson_destroy( bson * b );
+
+void bson_print( bson * b );
+void bson_print_raw( const char * bson , int depth );
+
+/* advances iterator to named field */
+/* returns bson_eoo (which is false) if field not found */
+bson_type bson_find(bson_iterator* it, const bson* obj, const char* name);
+
+void bson_iterator_init( bson_iterator * i , const char * bson );
+
+/* more returns true for eoo. best to loop with bson_iterator_next(&it) */
+bson_bool_t bson_iterator_more( const bson_iterator * i );
+bson_type bson_iterator_next( bson_iterator * i );
+
+bson_type bson_iterator_type( const bson_iterator * i );
+const char * bson_iterator_key( const bson_iterator * i );
+const char * bson_iterator_value( const bson_iterator * i );
+
+/* these convert to the right type (return 0 if non-numeric) */
+double bson_iterator_double( const bson_iterator * i );
+int bson_iterator_int( const bson_iterator * i );
+int64_t bson_iterator_long( const bson_iterator * i );
+
+/* false: boolean false, 0 in any type, or null */
+/* true: anything else (even empty strings and objects) */
+bson_bool_t bson_iterator_bool( const bson_iterator * i );
+
+/* these assume you are using the right type */
+double bson_iterator_double_raw( const bson_iterator * i );
+int bson_iterator_int_raw( const bson_iterator * i );
+int64_t bson_iterator_long_raw( const bson_iterator * i );
+bson_bool_t bson_iterator_bool_raw( const bson_iterator * i );
+bson_oid_t* bson_iterator_oid( const bson_iterator * i );
+
+/* these can also be used with bson_code and bson_symbol*/
+const char * bson_iterator_string( const bson_iterator * i );
+int bson_iterator_string_len( const bson_iterator * i );
+
+/* works with bson_code, bson_codewscope, and bson_string */
+/* returns NULL for everything else */
+const char * bson_iterator_code(const bson_iterator * i);
+
+/* calls bson_empty on scope if not a bson_codewscope */
+void bson_iterator_code_scope(const bson_iterator * i, bson * scope);
+
+/* both of these only work with bson_date */
+bson_date_t bson_iterator_date(const bson_iterator * i);
+time_t bson_iterator_time_t(const bson_iterator * i);
+
+int bson_iterator_bin_len( const bson_iterator * i );
+char bson_iterator_bin_type( const bson_iterator * i );
+const char * bson_iterator_bin_data( const bson_iterator * i );
+
+const char * bson_iterator_regex( const bson_iterator * i );
+const char * bson_iterator_regex_opts( const bson_iterator * i );
+
+/* these work with bson_object and bson_array */
+void bson_iterator_subobject(const bson_iterator * i, bson * sub);
+void bson_iterator_subiterator(const bson_iterator * i, bson_iterator * sub);
+
+/* str must be at least 24 hex chars + null byte */
+void bson_oid_from_string(bson_oid_t* oid, const char* str);
+void bson_oid_to_string(const bson_oid_t* oid, char* str);
+void bson_oid_gen(bson_oid_t* oid);
+
+time_t bson_oid_generated_time(bson_oid_t* oid); /* Gives the time the OID was created */
+
+/* ----------------------------
+   BUILDING
+   ------------------------------ */
+
+bson_buffer * bson_buffer_init( bson_buffer * b );
+bson_buffer * bson_ensure_space( bson_buffer * b , const int bytesNeeded );
+
+/**
+ * @return the raw data.  you either should free this OR call bson_destroy not both
+ */
+char * bson_buffer_finish( bson_buffer * b );
+void bson_buffer_destroy( bson_buffer * b );
+
+bson_buffer * bson_append_oid( bson_buffer * b , const char * name , const bson_oid_t* oid );
+bson_buffer * bson_append_new_oid( bson_buffer * b , const char * name );
+bson_buffer * bson_append_int( bson_buffer * b , const char * name , const int i );
+bson_buffer * bson_append_long( bson_buffer * b , const char * name , const int64_t i );
+bson_buffer * bson_append_double( bson_buffer * b , const char * name , const double d );
+bson_buffer * bson_append_string( bson_buffer * b , const char * name , const char * str );
+bson_buffer * bson_append_symbol( bson_buffer * b , const char * name , const char * str );
+bson_buffer * bson_append_code( bson_buffer * b , const char * name , const char * str );
+bson_buffer * bson_append_code_w_scope( bson_buffer * b , const char * name , const char * code , const bson * scope);
+bson_buffer * bson_append_binary( bson_buffer * b, const char * name, char type, const char * str, int len );
+bson_buffer * bson_append_bool( bson_buffer * b , const char * name , const bson_bool_t v );
+bson_buffer * bson_append_null( bson_buffer * b , const char * name );
+bson_buffer * bson_append_undefined( bson_buffer * b , const char * name );
+bson_buffer * bson_append_regex( bson_buffer * b , const char * name , const char * pattern, const char * opts );
+bson_buffer * bson_append_bson( bson_buffer * b , const char * name , const bson* bson);
+bson_buffer * bson_append_element( bson_buffer * b, const char * name_or_null, const bson_iterator* elem);
+
+/* these both append a bson_date */
+bson_buffer * bson_append_date(bson_buffer * b, const char * name, bson_date_t millis);
+bson_buffer * bson_append_time_t(bson_buffer * b, const char * name, time_t secs);
+
+bson_buffer * bson_append_start_object( bson_buffer * b , const char * name );
+bson_buffer * bson_append_start_array( bson_buffer * b , const char * name );
+bson_buffer * bson_append_finish_object( bson_buffer * b );
+
+void bson_numstr(char* str, int i);
+void bson_incnumstr(char* str);
+
+
+/* ------------------------------
+   ERROR HANDLING - also used in mongo code
+   ------------------------------ */
+
+void * bson_malloc(int size); /* checks return value */
+
+/* bson_err_handlers shouldn't return!!! */
+typedef void(*bson_err_handler)(const char* errmsg);
+
+/* returns old handler or NULL */
+/* default handler prints error then exits with failure*/
+bson_err_handler set_bson_err_handler(bson_err_handler func);
+
+
+
+/* does nothing is ok != 0 */
+void bson_fatal( int ok );
+int bson_fatal_msg( int ok, const char* msg );
+
+MONGO_EXTERN_C_END
+#endif

data/ext/oboe_metal/src/bson/platform_hacks.h

@@ -0,0 +1,91 @@
+/* platform_hacks.h */
+/*    Copyright 2009, 2010 10gen Inc.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+
+/* all platform-specific ifdefs should go here */
+
+#ifndef _PLATFORM_HACKS_H_
+#define _PLATFORM_HACKS_H_
+
+#ifdef __GNUC__
+#define MONGO_INLINE static __inline__
+#else
+#define MONGO_INLINE static
+#endif
+
+#ifdef __cplusplus
+#define MONGO_EXTERN_C_START extern "C" {
+#define MONGO_EXTERN_C_END }
+#else
+#define MONGO_EXTERN_C_START
+#define MONGO_EXTERN_C_END
+#endif
+
+
+#if defined(MONGO_HAVE_STDINT) || __STDC_VERSION__ >= 199901L
+#include <stdint.h>
+#elif defined(MONGO_HAVE_UNISTD)
+#include <unistd.h>
+#elif defined(MONGO_USE__INT64)
+typedef __int64 int64_t;
+#elif defined(MONGO_USE_LONG_LONG_INT)
+typedef long long int int64_t;
+#else
+#error must have a 64bit int type
+#endif
+
+/* big endian is only used for OID generation. little is used everywhere else */
+#ifdef MONGO_BIG_ENDIAN
+#define bson_little_endian64(out, in) ( bson_swap_endian64(out, in) )
+#define bson_little_endian32(out, in) ( bson_swap_endian32(out, in) )
+#define bson_big_endian64(out, in) ( memcpy(out, in, 8) )
+#define bson_big_endian32(out, in) ( memcpy(out, in, 4) )
+#else
+#define bson_little_endian64(out, in) ( memcpy(out, in, 8) )
+#define bson_little_endian32(out, in) ( memcpy(out, in, 4) )
+#define bson_big_endian64(out, in) ( bson_swap_endian64(out, in) )
+#define bson_big_endian32(out, in) ( bson_swap_endian32(out, in) )
+#endif
+
+MONGO_EXTERN_C_START
+
+MONGO_INLINE void bson_swap_endian64(void* outp, const void* inp){
+    const char *in = (const char*)inp;
+    char *out = (char*)outp;
+
+    out[0] = in[7];
+    out[1] = in[6];
+    out[2] = in[5];
+    out[3] = in[4];
+    out[4] = in[3];
+    out[5] = in[2];
+    out[6] = in[1];
+    out[7] = in[0];
+
+}
+MONGO_INLINE void bson_swap_endian32(void* outp, const void* inp){
+    const char *in = (const char*)inp;
+    char *out = (char*)outp;
+
+    out[0] = in[3];
+    out[1] = in[2];
+    out[2] = in[1];
+    out[3] = in[0];
+}
+
+MONGO_EXTERN_C_END
+
+#endif

data/ext/oboe_metal/src/oboe.h

@@ -0,0 +1,275 @@
+#ifndef LIBOBOE_H
+#define LIBOBOE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <sys/types.h>
+#include <inttypes.h>
+#include "bson/bson.h"
+
+#define OBOE_SAMPLE_RATE_DEFAULT 300000 // 30%
+#define OBOE_SAMPLE_RESOLUTION 1000000
+
+#define OBOE_MAX_TASK_ID_LEN 20
+#define OBOE_MAX_OP_ID_LEN 8
+#define OBOE_MAX_METADATA_PACK_LEN 512
+
+#define XTR_CURRENT_VERSION 1
+#define XTR_UDP_PORT 7831
+
+
+// structs
+
+typedef struct oboe_ids {
+    uint8_t task_id[OBOE_MAX_TASK_ID_LEN];
+    uint8_t op_id[OBOE_MAX_OP_ID_LEN];
+} oboe_ids_t;
+
+typedef struct oboe_metadata {
+    oboe_ids_t  ids;
+    size_t      task_len;
+    size_t      op_len;
+} oboe_metadata_t;
+
+typedef struct oboe_event {
+    oboe_metadata_t metadata;
+    bson_buffer     bbuf;
+    char *          bb_str;
+} oboe_event_t;
+
+
+// oboe_metadata
+
+int oboe_metadata_init      (oboe_metadata_t *);
+int oboe_metadata_destroy   (oboe_metadata_t *);
+
+int oboe_metadata_is_valid   (const oboe_metadata_t *);
+
+void oboe_metadata_copy     (oboe_metadata_t *, const oboe_metadata_t *);
+
+void oboe_metadata_random   (oboe_metadata_t *);
+
+int oboe_metadata_set_lengths   (oboe_metadata_t *, size_t, size_t);
+int oboe_metadata_create_event  (const oboe_metadata_t *, oboe_event_t *);
+
+int oboe_metadata_tostr     (const oboe_metadata_t *, char *, size_t);
+int oboe_metadata_fromstr   (oboe_metadata_t *, const char *, size_t);
+
+
+// oboe_event
+
+int oboe_event_init     (oboe_event_t *, const oboe_metadata_t *);
+int oboe_event_destroy  (oboe_event_t *);
+
+int oboe_event_add_info (oboe_event_t *, const char *, const char *);
+int oboe_event_add_info_binary (oboe_event_t *, const char *, const char *, size_t);
+int oboe_event_add_info_int64 (oboe_event_t *, const char *, const int64_t);
+int oboe_event_add_info_double (oboe_event_t *, const char *, const double);
+int oboe_event_add_info_bool (oboe_event_t *, const char *, const int);
+int oboe_event_add_info_fmt (oboe_event_t *, const char *key, const char *fmt, ...);
+int oboe_event_add_info_bson (oboe_event_t *, const char *key, const bson *val);
+int oboe_event_add_edge (oboe_event_t *, const oboe_metadata_t *);
+int oboe_event_add_edge_fromstr(oboe_event_t *, const char *, size_t);
+
+
+// oboe_context
+
+oboe_metadata_t *oboe_context_get();
+void oboe_context_set(oboe_metadata_t *);
+int oboe_context_set_fromstr(const char *, size_t);
+
+void oboe_context_clear();
+
+int oboe_context_is_valid();
+
+
+// oboe_reporter
+
+typedef ssize_t (*reporter_send)(void *, const char *, size_t);
+typedef int (*reporter_destroy)(void *);
+
+typedef struct oboe_reporter {
+    void *              descriptor;
+    reporter_send       send;
+    reporter_destroy    destroy;
+} oboe_reporter_t;
+
+int oboe_reporter_udp_init  (oboe_reporter_t *, const char *, const char *);
+int oboe_reporter_file_init (oboe_reporter_t *, const char *);
+
+int oboe_reporter_send(oboe_reporter_t *, oboe_metadata_t *, oboe_event_t *);
+int oboe_reporter_destroy(oboe_reporter_t *);
+ssize_t oboe_reporter_udp_send(void *desc, const char *data, size_t len);
+
+
+// initialization
+
+void oboe_init();
+
+
+// Settings interface
+
+#define OBOE_SETTINGS_VERSION 1
+#define OBOE_SETTINGS_MAGIC_NUMBER 0x6f626f65
+#define OBOE_SETTINGS_TYPE_SKIP 0
+#define OBOE_SETTINGS_TYPE_STOP 1
+#define OBOE_SETTINGS_TYPE_DEFAULT_SAMPLE_RATE 2
+#define OBOE_SETTINGS_TYPE_LAYER_SAMPLE_RATE 3
+#define OBOE_SETTINGS_TYPE_LAYER_APP_SAMPLE_RATE 4
+#define OBOE_SETTINGS_TYPE_LAYER_HTTPHOST_SAMPLE_RATE 5
+#define OBOE_SETTINGS_TYPE_CONFIG_STRING 6
+#define OBOE_SETTINGS_TYPE_CONFIG_INT 7
+#define OBOE_SETTINGS_FLAG_OK             0x0
+#define OBOE_SETTINGS_FLAG_INVALID        0x1
+#define OBOE_SETTINGS_FLAG_OVERRIDE       0x2
+#define OBOE_SETTINGS_FLAG_SAMPLE_START   0x4
+#define OBOE_SETTINGS_FLAG_SAMPLE_THROUGH 0x8
+#define OBOE_SETTINGS_FLAG_SAMPLE_THROUGH_ALWAYS 0x10
+#define OBOE_SETTINGS_FLAG_SAMPLE_AVW_ALWAYS     0x20
+#define OBOE_SETTINGS_MAX_STRLEN 256
+
+#define OBOE_SETTINGS_UNSET -1
+#define OBOE_SETTINGS_MIN_REFRESH_INTERVAL 30
+
+// Value for "SampleSource" info key
+// where was the sample rate specified? (oboe settings, config file, hard-coded default, etc)
+#define OBOE_SAMPLE_RATE_SOURCE_FILE 1
+#define OBOE_SAMPLE_RATE_SOURCE_DEFAULT 2
+#define OBOE_SAMPLE_RATE_SOURCE_OBOE 3
+#define OBOE_SAMPLE_RATE_SOURCE_LAST_OBOE 4
+#define OBOE_SAMPLE_RATE_SOURCE_DEFAULT_MISCONFIGURED 5
+#define OBOE_SAMPLE_RATE_SOURCE_OBOE_DEFAULT 6 
+
+#define OBOE_SAMPLE_RESOLUTION 1000000
+
+// Used to convert to settings flags:
+#define OBOE_TRACE_NEVER   0
+#define OBOE_TRACE_ALWAYS  1
+#define OBOE_TRACE_THROUGH 2
+
+typedef struct {
+    volatile uint32_t magic;
+    volatile uint32_t timestamp;
+    volatile uint16_t type;
+    volatile uint16_t flags;
+    volatile uint32_t value;
+    uint32_t _pad;
+    char layer[OBOE_SETTINGS_MAX_STRLEN];
+    char arg[OBOE_SETTINGS_MAX_STRLEN];
+} __attribute__((packed)) oboe_settings_t;
+
+// Current settings configuration:
+typedef struct {
+    int tracing_mode;          // loaded from config file
+    int sample_rate;           // loaded from config file
+    int default_sample_rate;   // default sample rate (fallback)
+    oboe_settings_t *settings; // cached settings, updated by tracelyzer (init to NULL)
+    int last_auto_sample_rate; // stores last known automatic sampling rate 
+    uint16_t last_auto_flags;  // stores last known flags associated with above 
+    uint32_t last_auto_timestamp; // timestamp from last *settings lookup
+    uint32_t last_refresh;        // last refresh time
+} oboe_settings_cfg_t;
+
+oboe_settings_t* oboe_settings_get(uint16_t type, const char* layer, const char* arg);
+oboe_settings_t* oboe_settings_get_layer_tracing_mode(const char* layer);
+oboe_settings_t* oboe_settings_get_layer_sample_rate(const char* layer);
+oboe_settings_t* oboe_settings_get_layer_app_sample_rate(const char* layer, const char* app);
+uint32_t oboe_settings_get_latest_timestamp(const char* layer);
+int oboe_settings_get_value(oboe_settings_t *s, int *outval, unsigned short *outflags, uint32_t *outtimestamp);
+
+oboe_settings_cfg_t* oboe_settings_cfg_get();
+void oboe_settings_cfg_init(oboe_settings_cfg_t *cfg);
+void oboe_settings_cfg_tracing_mode_set(int new_mode);
+void oboe_settings_cfg_sample_rate_set(int new_rate);
+
+/**
+ * Check if this request should be sampled (deprecated - use oboe_sample_layer() instead).
+ *
+ * @param layer Layer name as used in oboe_settings_t.layer (may be NULL to use default settings)
+ * @param xtrace X-Trace ID string from an HTTP request or higher layer (NULL or empty string if not present).
+ * @param cfg The settings configuration to use for this evaluation.
+ * @param sample_rate_out The sample rate used to check if this request should be sampled
+ *          (output - may be zero if not used).
+ * @param sample_source_out The OBOE_SAMPLE_RATE_SOURCE used to check if this request
+ *          should be sampled (output - may be zero if not used).
+ * @return Non-zero if the given layer should be sampled.
+ */
+int oboe_sample_request(const char *layer, const char *in_xtrace, oboe_settings_cfg_t *cfg,
+                      int *sample_rate_out, int *sample_source_out);
+int oboe_rand_get_value();
+
+/**
+ * Check if this request should be sampled.
+ *
+ * Checks for sample rate flags and settings for the specified layer, considers any
+ * special features in the X-Trace and X-TV-Meta HTTP headers, and, if appropriate,
+ * rolls the virtual dice to decide if this request should be sampled.
+ *
+ * This replaces oboe_sample_request with a version that uses the settings
+ * configuration kept in thread-local storage and takes the X-TV-Meta HTTP
+ * header value in order to support AppView Web integration.
+ *
+ * @param layer Layer name as used in oboe_settings_t.layer (may be NULL to use default settings)
+ * @param xtrace X-Trace ID string from an HTTP request or higher layer (NULL or empty string if not present).
+ * @param tv_meta AppView Web ID from X-TV-Meta HTTP header or higher layer (NULL or empty string if not present).
+ * @param sample_rate_out The sample rate used to check if this request should be sampled
+ *          (output - may be zero if not used).
+ * @param sample_source_out The OBOE_SAMPLE_RATE_SOURCE used to check if this request
+ *          should be sampled (output - may be zero if not used).
+ * @return Non-zero if the given layer should be sampled.
+ */
+int oboe_sample_layer(
+    const char *layer,
+    const char *xtrace,
+    const char *tv_meta,
+    int *sample_rate_out,
+    int *sample_source_out
+);
+
+/* Oboe configuration interface. */
+
+/**
+ * Check if the Oboe library is compatible with a given version.revision.
+ *
+ * This will succeed if the library is at least as recent as specified and if no
+ * definitions have been removed since that revision.
+ *
+ * @param version The library's version number which increments every time the API changes.
+ * @param revision The revision of the current version of the library.
+ * @return Non-zero if the Oboe library is considered compatible with the specified revision.
+ */
+extern int oboe_config_check_version(int version, int revision);
+
+/**
+ * Get the Oboe library version number.
+ *
+ * This number increments whenever the API is changed.
+ *
+ * @return The library's version number or -1 if the version is not known.
+ */
+extern int oboe_config_get_version();
+
+/**
+ * Get the Oboe library revision number.
+ *
+ * This is the revision of the current version which is updated whenever
+ * compatible changes are made to the API/ABI (ie. additions).
+ *
+ * @return The library's revision number or -1 if not known.
+ */
+extern int oboe_config_get_revision();
+
+/*
+ * Get the Oboe library version as a string.
+ *
+ * Returns the complete VERSION string or null
+ */
+const char* oboe_config_get_version_string();
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // LIBOBOE_H