Housekeeping: update deps, fix trace protobuf path, regenerate files (#126)

housekeeping: update deps, fix trace protobuf path, regenerate files

Author: deadtrickster

bin/set-edoc-hidden

@@ -1,10 +1,12 @@
 #!/usr/bin/env sh
 
-[ -f "$1" ] || exit 1
-
-FILE="$1"
 HIDDEN="%% @hidden"
 
-if [ "$(head -n 1 $FILE)" != "$HIDDEN" ]; then
-    echo "0a\n$HIDDEN\n.\nw" | ed "$FILE" >/dev/null
-fi
+for FILE in "$@"
+do
+    [ -f "$FILE" ] || exit 1
+
+    if [ "$(head -n 1 $FILE)" != "$HIDDEN" ]; then
+        echo "0a\n$HIDDEN\n.\nw" | ed "$FILE" >/dev/null
+    fi
+done

doc/README.md

@@ -192,6 +192,7 @@ $ rebar3 protobuf compile
 <tr><td><a href="oc_span.md" class="module">oc_span</a></td></tr>
 <tr><td><a href="oc_span_ctx_binary.md" class="module">oc_span_ctx_binary</a></td></tr>
 <tr><td><a href="oc_span_ctx_header.md" class="module">oc_span_ctx_header</a></td></tr>
+<tr><td><a href="oc_span_sweeper.md" class="module">oc_span_sweeper</a></td></tr>
 <tr><td><a href="oc_span_transform.md" class="module">oc_span_transform</a></td></tr>
 <tr><td><a href="oc_stat.md" class="module">oc_stat</a></td></tr>
 <tr><td><a href="oc_stat_aggregation.md" class="module">oc_stat_aggregation</a></td></tr>

doc/edoc-info

@@ -3,11 +3,11 @@
 {modules,[oc_reporter,oc_reporter_noop,oc_reporter_sequential,
           oc_reporter_stdout,oc_reporter_zipkin,oc_sampler,oc_sampler_always,
           oc_sampler_impl,oc_sampler_never,oc_sampler_probability,oc_server,
-          oc_span,oc_span_ctx_binary,oc_span_ctx_header,oc_span_transform,
-          oc_stat,oc_stat_aggregation,oc_stat_aggregation_count,
-          oc_stat_aggregation_distribution,oc_stat_aggregation_latest,
-          oc_stat_aggregation_sum,oc_stat_config,oc_stat_exporter,
-          oc_stat_exporter_stdout,oc_stat_measure,oc_stat_transform,
-          oc_stat_unit,oc_stat_view,oc_std_encoder,oc_tag_ctx_binary,
-          oc_tag_ctx_header,oc_tags,oc_trace,ocp,opencensus,opencensus_app,
-          opencensus_sup]}.
+          oc_span,oc_span_ctx_binary,oc_span_ctx_header,oc_span_sweeper,
+          oc_span_transform,oc_stat,oc_stat_aggregation,
+          oc_stat_aggregation_count,oc_stat_aggregation_distribution,
+          oc_stat_aggregation_latest,oc_stat_aggregation_sum,oc_stat_config,
+          oc_stat_exporter,oc_stat_exporter_stdout,oc_stat_measure,
+          oc_stat_transform,oc_stat_unit,oc_stat_view,oc_std_encoder,
+          oc_tag_ctx_binary,oc_tag_ctx_header,oc_tags,oc_trace,ocp,opencensus,
+          opencensus_app,opencensus_sup]}.

doc/index.md

@@ -80,6 +80,29 @@ Headers = [{oc_span_ctx_header:field_name(), EncodedSpanCtx}],
 
 [Prometheus](https://github.com/deadtrickster/opencensus-erlang-prometheus): Exports spans as Prometheus metrics.
 
+[DataDog][oc_datadog]: Export spans to DataDog APM
+
+#### <a name="Sweeper">Cleaning Up Abandoned Spans</a> ####
+
+Active spans have their data stored in an ETS table. When a span is finished it is removed from the active spans table and moved to a table handled by the reporter process. If a span isn't finished, either because of a mistake in the code creating and finishing spans, or the process with open spans crashes before being able to finish the spans, there would be a memory leak.
+
+The `oc_span_sweeper` process checks for active spans which started greater than a configurable (`span_ttl`) duration, with a default of 5 minutes. There are 4 strategies for handling a span that is older than the time to live (`strategy`):
+
+* `drop`: Spans are removed from the active span table and a log message is written with the total number of spans being dropped in this sweep.
+* `finish`: Each span is finished as is.
+* `failed_attribute_and_finish`: An attribute `finished_by_sweeper` with value `true` is added to the span data and then the span is finished.
+* Custom function: Any funtion with type spec `fun((opencensus:span()) -> ok)` can be used. Note that the span is not removed from the active spans table if this method is used and the function must do the removal if it deems it necessary.
+
+An example configuration in `sys.config` to run a check every 5 minutes, dropping active spans older than 5 minutes can be found in the example project `helloworld`, `examples/helloworld/config/sys.config`, the sweeper snippet looks like:
+
+``` erlang
+{sweeper, #{interval => 300000,
+            strategy => drop,
+            span_ttl => 300000}}
+```
+
+To disable sweeping set `interval` to `infinity`.
+
 ### <a name="Logging">Logging</a> ###
 
 OTP-21 includes a new logging framework. When a context is created with a span (for example `ocp:with_child_span/1` or `oc_trace:with_child_span/2`) opencensus will update the current process's logger metadata to include the `trace_id`, `span_id` and `trace_options` with the latest ids under the key `span_ctx`, `trace_options` will be `1` if the trace is enabled. To use these with the default formatter you can create a custom template that includes them if they exist like so:
@@ -147,7 +170,9 @@ oc_stat_view:subscribe(#{name => "opencensus.io/http/server/server_latency",
 ```
 prometheus_registry:register_collector(oc_stat_exporter_prometheus)
 ```
-  
+
+[DogStatsD][oc_datadog]: Export stat views as DataDog metrics.
+
 ### Development
 
 ```sh
@@ -168,3 +193,5 @@ Language independent interface types for Census are found in the `opencensus-pro
 $ git clone https://github.com/census-instrumentation/opencensus-proto priv/opencensus-proto
 $ rebar3 protobuf compile
 ```
+
+[oc_datadog]: https://github.com/hauleth/oc_datadog

doc/oc_reporter.md

@@ -17,13 +17,19 @@ __This module defines the `oc_reporter` behaviour.__<br /> Required callback fun
 ## Function Index ##
 
 
-<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#handle_call-3">handle_call/3</a></td><td></td></tr><tr><td valign="top"><a href="#handle_cast-2">handle_cast/2</a></td><td></td></tr><tr><td valign="top"><a href="#handle_info-2">handle_info/2</a></td><td></td></tr><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-0">start_link/0</a></td><td></td></tr><tr><td valign="top"><a href="#store_span-1">store_span/1</a></td><td></td></tr><tr><td valign="top"><a href="#terminate-2">terminate/2</a></td><td></td></tr></table>
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#code_change-3">code_change/3</a></td><td></td></tr><tr><td valign="top"><a href="#handle_call-3">handle_call/3</a></td><td></td></tr><tr><td valign="top"><a href="#handle_cast-2">handle_cast/2</a></td><td></td></tr><tr><td valign="top"><a href="#handle_info-2">handle_info/2</a></td><td></td></tr><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-0">start_link/0</a></td><td></td></tr><tr><td valign="top"><a href="#store_span-1">store_span/1</a></td><td></td></tr><tr><td valign="top"><a href="#terminate-2">terminate/2</a></td><td></td></tr></table>
 
 
 <a name="functions"></a>
 
 ## Function Details ##
 
+<a name="code_change-3"></a>
+
+### code_change/3 ###
+
+`code_change(X1, State, X3) -> any()`
+
 <a name="handle_call-3"></a>
 
 ### handle_call/3 ###

doc/oc_span_sweeper.md

@@ -0,0 +1,56 @@
+
+
+# Module oc_span_sweeper #
+* [Function Index](#index)
+* [Function Details](#functions)
+
+__Behaviours:__ [`gen_statem`](gen_statem.md).
+
+<a name="index"></a>
+
+## Function Index ##
+
+
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#callback_mode-0">callback_mode/0</a></td><td></td></tr><tr><td valign="top"><a href="#code_change-4">code_change/4</a></td><td></td></tr><tr><td valign="top"><a href="#handle_event-4">handle_event/4</a></td><td></td></tr><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-0">start_link/0</a></td><td></td></tr><tr><td valign="top"><a href="#terminate-3">terminate/3</a></td><td></td></tr></table>
+
+
+<a name="functions"></a>
+
+## Function Details ##
+
+<a name="callback_mode-0"></a>
+
+### callback_mode/0 ###
+
+`callback_mode() -> any()`
+
+<a name="code_change-4"></a>
+
+### code_change/4 ###
+
+`code_change(X1, State, Data, X4) -> any()`
+
+<a name="handle_event-4"></a>
+
+### handle_event/4 ###
+
+`handle_event(X1, X2, X3, Data) -> any()`
+
+<a name="init-1"></a>
+
+### init/1 ###
+
+`init(X1) -> any()`
+
+<a name="start_link-0"></a>
+
+### start_link/0 ###
+
+`start_link() -> any()`
+
+<a name="terminate-3"></a>
+
+### terminate/3 ###
+
+`terminate(Reason, State, Data) -> any()`
+

doc/oc_stat.md

@@ -26,7 +26,7 @@ Records one or multiple measurements with the same tags at once.</td></tr></tabl
 ### export/0 ###
 
 <pre><code>
-export() -&gt; <a href="oc_stat_view.md#type-view_data">oc_stat_view:view_data()</a>
+export() -&gt; [<a href="oc_stat_view.md#type-view_data">oc_stat_view:view_data()</a>]
 </code></pre>
 <br />
 

doc/oc_stat_aggregation.md

@@ -2,8 +2,53 @@
 
 # Module oc_stat_aggregation #
 * [Description](#description)
+* [Data Types](#types)
 
 Aggregation represents a data aggregation method.
 
 __This module defines the `oc_stat_aggregation` behaviour.__<br /> Required callback functions: `init/3`, `type/0`, `add_sample/4`, `export/2`, `clear_rows/2`.
 
+<a name="types"></a>
+
+## Data Types ##
+
+
+
+
+### <a name="type-data">data()</a> ###
+
+
+<pre><code>
+data() = <a href="#type-data">data</a>(latest, number()) | <a href="#type-data">data</a>(count, number()) | <a href="#type-data">data</a>(sum, #{count =&gt; non_neg_integer(), mean =&gt; number(), sum =&gt; number()}) | <a href="#type-data">data</a>(distribution, #{count =&gt; non_neg_integer(), mean =&gt; number(), sum =&gt; number(), buckets =&gt; [{number(), non_neg_integer()}]})
+</code></pre>
+
+
+
+
+### <a name="type-data">data()</a> ###
+
+
+<pre><code>
+data(Type, AggregationValue) = #{type =&gt; Type, rows =&gt; <a href="#type-data_rows">data_rows</a>(AggregationValue)}
+</code></pre>
+
+
+
+
+### <a name="type-data_rows">data_rows()</a> ###
+
+
+<pre><code>
+data_rows(AggregationValue) = [#{tags =&gt; <a href="#type-tv">tv()</a>, value =&gt; AggregationValue}]
+</code></pre>
+
+
+
+
+### <a name="type-tv">tv()</a> ###
+
+
+<pre><code>
+tv() = [<a href="oc_tags.md#type-value">oc_tags:value()</a>]
+</code></pre>
+

elvis.config

@@ -5,7 +5,7 @@
     {config,
      [#{dirs => ["src"],
         filter => "*.erl",
-        ignore => ["src/oc_trace_pb.erl"],
+        ignore => ["src/oc_trace_pb.erl", "src/oc_trace_config_pb.erl"],
         rules => [{elvis_style, god_modules, #{ignore => [ocp]}},
                   {elvis_style, no_debug_call, #{ignore => [oc_reporter_stdout, oc_stat_exporter_stdout]}},
                   {elvis_style, dont_repeat_yourself, #{min_complexity => 20}},

include/oc_trace_config_pb.hrl

@@ -0,0 +1,42 @@
+%% -*- coding: utf-8 -*-
+%% Automatically generated, do not edit
+%% Generated by gpb_compile version 4.4.1
+
+-ifndef(oc_trace_config_pb).
+-define(oc_trace_config_pb, true).
+
+-define(oc_trace_config_pb_gpb_version, "4.4.1").
+
+-ifndef('TRACE_CONFIG_PB_PB_H').
+-define('TRACE_CONFIG_PB_PB_H', true).
+-record(trace_config_pb,
+        {sampler                :: {probability_sampler, oc_trace_config_pb:probability_sampler_pb()} | {constant_sampler, oc_trace_config_pb:constant_sampler_pb()} | {rate_limiting_sampler, oc_trace_config_pb:rate_limiting_sampler_pb()} | undefined, % oneof
+         max_number_of_attributes = 0 :: integer() | undefined, % = 4, 32 bits
+         max_number_of_annotations = 0 :: integer() | undefined, % = 5, 32 bits
+         max_number_of_message_events = 0 :: integer() | undefined, % = 6, 32 bits
+         max_number_of_links = 0 :: integer() | undefined % = 7, 32 bits
+        }).
+-endif.
+
+-ifndef('PROBABILITY_SAMPLER_PB_PB_H').
+-define('PROBABILITY_SAMPLER_PB_PB_H', true).
+-record(probability_sampler_pb,
+        {samplingProbability = 0.0 :: float() | integer() | infinity | '-infinity' | nan | undefined % = 1
+        }).
+-endif.
+
+-ifndef('CONSTANT_SAMPLER_PB_PB_H').
+-define('CONSTANT_SAMPLER_PB_PB_H', true).
+-record(constant_sampler_pb,
+        {decision = false       :: boolean() | 0 | 1 | undefined % = 1
+        }).
+-endif.
+
+-ifndef('RATE_LIMITING_SAMPLER_PB_PB_H').
+-define('RATE_LIMITING_SAMPLER_PB_PB_H', true).
+-record(rate_limiting_sampler_pb,
+        {qps = 0                :: integer() | undefined % = 1, 32 bits
+        }).
+-endif.
+
+-endif.