From 2bca758058a18d2004a7ddce79d988667ff9053f Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Thu, 9 Jul 2020 07:48:10 -0600 Subject: [PATCH] fix docs --- README.md | 2 +- doc/README.md | 11 +++++------ doc/build.sh | 2 +- doc/edoc-info | 14 +++++++------- doc/index.md | 35 +++++++++++++---------------------- doc/oc_reporter.md | 22 +++++++++++++++++++++- doc/oc_span.md | 8 ++++---- doc/oc_trace.md | 6 +++--- doc/opencensus.md | 14 ++++++++++++-- rebar.lock | 9 +++++++-- src/oc_reporter.erl | 2 +- 11 files changed, 75 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 0dbc41c..a43a29a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # OpenCensus Erlang library # -__Version:__ 0.5.0 +__Version:__ 0.9.3 ## Erlang stats collection and distributed tracing framework diff --git a/doc/README.md b/doc/README.md index ea96b91..7b8e313 100644 --- a/doc/README.md +++ b/doc/README.md @@ -180,11 +180,12 @@ $ rebar3 protobuf compile + + + - - + - @@ -194,8 +195,6 @@ $ rebar3 protobuf compile - - @@ -211,11 +210,11 @@ $ rebar3 protobuf compile - + diff --git a/doc/build.sh b/doc/build.sh index 6c8ba0c..dc0f7a6 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -9,7 +9,7 @@ make # fix internal doc links sed -i 's/https:\/\/github\.com\/doc\/\(.*\)\.md/\1.html/g' *.html -sed -i 's/\"\([a-zA-Z_-]*\)\.md\([a-zA-Z_-#]*\)\"/\"\1.html\2\"/g' *.html +sed -i 's/\"\([a-zA-Z_-]*\)\.md\([a-zA-Z_#-]*\)\"/\"\1.html\2\"/g' *.html sed -i 's/\"doc\/\([a-zA-Z_-]*\)\.md\"/\"\1.html\"/g' *.html sed -i 's/\"\([a-zA-Z_-]*\)\.md\"/\"\1.html\"/g' *.html sed -i 's/
//g' *.html diff --git a/doc/edoc-info b/doc/edoc-info index c365fda..23fd156 100644 --- a/doc/edoc-info +++ b/doc/edoc-info @@ -1,14 +1,14 @@ %% encoding: UTF-8 {application,opencensus}. -{modules,[oc_producer,oc_producer_registry,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_period_or_count,oc_sampler_probability,oc_self_producer, - oc_server,oc_span,oc_span_ctx_binary,oc_span_ctx_header, +{modules,[oc_producer,oc_producer_registry,oc_propagation_binary, + oc_propagation_http_b3,oc_propagation_http_tracecontext,oc_reporter, + oc_reporter_pid,oc_reporter_stdout,oc_sampler,oc_sampler_always, + oc_sampler_impl,oc_sampler_never,oc_sampler_period_or_count, + oc_sampler_probability,oc_self_producer,oc_server,oc_span, 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, + oc_stat_transform,oc_stat_unit,oc_stat_view,oc_tag_ctx_binary, + oc_tag_ctx_header,oc_tags,oc_trace,oc_tracestate,ocp,opencensus, opencensus_app,opencensus_sup]}. diff --git a/doc/index.md b/doc/index.md index 2850809..a43a29a 100644 --- a/doc/index.md +++ b/doc/index.md @@ -2,7 +2,7 @@ # OpenCensus Erlang library # -__Version:__ 0.5.0 +__Version:__ 0.9.3 ## Erlang stats collection and distributed tracing framework @@ -52,33 +52,33 @@ some_fun() -> end). ``` -More details on working with spans can be found [here](span.md) and in the modules documentation for [ocp](ocp.md), [oc_trace](oc_trace.md) and [oc_span](oc_span.md). +More details on working with spans can be found [here](doc/span.md) and in the modules documentation for [ocp](doc/ocp.md), [oc_trace](doc/oc_trace.md) and [oc_span](doc/oc_span.md). #### Propagating Span Context #### -Opencensus comes with two forms of span context encoding for sending over the wire. `oc_span_ctx_header` encodes a span context suitable for transfering as an HTTP header and `oc_span_ctx_binary` will encode and decode a binary form used in GRPC and other binary protocols. +Builtin support for encoding and decoding span context from HTTP headers comes in two formats: -For example, creating the header for sending with an HTTP client might look like: +* [W3C Trace Context](https://www.w3.org/TR/trace-context/) +* [B3](https://github.com/openzipkin/b3-propagation) -```erlang -EncodedSpanCtx = oc_span_ctx_header:encode(ocp:current_span_ctx()), -Headers = [{oc_span_ctx_header:field_name(), EncodedSpanCtx}], -``` +Additionally `oc_propagation_binary` will encode and decode a binary form used for GRPC and other binary protocols. #### Samplers #### -[oc_sampler_never](oc_sampler_never.md): Never enable a new trace, but keeps a trace enabled if its propagated context is enabled. +[oc_sampler_never](doc/oc_sampler_never.md): Never enable a new trace, but keeps a trace enabled if its propagated context is enabled. -[oc_sampler_always](oc_sampler_always.md): Enable every new trace for sampling. +[oc_sampler_always](doc/oc_sampler_always.md): Enable every new trace for sampling. -[oc_sampler_probability](oc_sampler_probability.md): Takes a probability, default 0.5, that any new trace will be sampled. +[oc_sampler_probability](doc/oc_sampler_probability.md): Takes a probability, default 0.5, that any new trace will be sampled. #### Reporters #### -[Google Cloud Trace](https://github.com/tsloughter/oc_google_reporter): Support for v1 in master, v2 and grpc coming soon; +[Zipkin](https://github.com/opencensus-beam/opencensus_zipkin): Zipkin v2 reporter. -[Prometheus](https://github.com/deadtrickster/opencensus-erlang-prometheus): Exports spans as Prometheus metrics. +[Google Cloud Trace](https://github.com/opencensus-beam/oc_google_reporter): Support for v1 in master, v2 and grpc coming soon; + +[Prometheus](https://github.com/opencensus-beam/prometheus): Exports spans as Prometheus metrics. [DataDog][oc_datadog]: Export spans to DataDog APM @@ -185,13 +185,4 @@ Running tests: $ rebar3 ct ``` -#### Updating OpenCensus standard protobuf encoder and decoder - -Language independent interface types for Census are found in the `opencensus-proto` repo. The opencensus Erlang app provides functionality for converting from the apps internal representation to the standard protobuf interface. Below are the steps to update the Erlang module and header for encoding and decoding the protobufs: - -```sh -$ git clone https://github.com/census-instrumentation/opencensus-proto priv/opencensus-proto -$ rebar3 protobuf compile -``` - [oc_datadog]: https://github.com/hauleth/oc_datadog diff --git a/doc/oc_reporter.md b/doc/oc_reporter.md index 548bf24..b271f79 100644 --- a/doc/oc_reporter.md +++ b/doc/oc_reporter.md @@ -17,7 +17,8 @@ __This module defines the `oc_reporter` behaviour.__
Required callback fun ## Function Index ## -
oc_producer
oc_producer_registry
oc_propagation_binary
oc_propagation_http_b3
oc_propagation_http_tracecontext
oc_reporter
oc_reporter_noop
oc_reporter_sequential
oc_reporter_pid
oc_reporter_stdout
oc_reporter_zipkin
oc_sampler
oc_sampler_always
oc_sampler_impl
oc_self_producer
oc_server
oc_span
oc_span_ctx_binary
oc_span_ctx_header
oc_span_sweeper
oc_span_transform
oc_stat
oc_stat_transform
oc_stat_unit
oc_stat_view
oc_std_encoder
oc_tag_ctx_binary
oc_tag_ctx_header
oc_tags
oc_trace
oc_tracestate
ocp
opencensus
opencensus_app
code_change/3
handle_call/3
handle_cast/2
handle_info/2
init/1
start_link/0
store_span/1
terminate/2
+
code_change/3
handle_call/3
handle_cast/2
handle_info/2
init/1
register/1Equivalent to register(Reporter, []).
register/2 +Register new traces reporter Reporter with Config.
start_link/0
store_span/1
terminate/2
@@ -54,6 +55,25 @@ __This module defines the `oc_reporter` behaviour.__
Required callback fun `init(Args) -> any()` + + +### register/1 ### + +`register(Reporter) -> any()` + +Equivalent to [`register(Reporter, [])`](#register-2). + + + +### register/2 ### + +

+register(Reporter::module(), Options::term()) -> ok
+
+
+ +Register new traces reporter `Reporter` with `Config`. + ### start_link/0 ### diff --git a/doc/oc_span.md b/doc/oc_span.md index ba03338..cc02a98 100644 --- a/doc/oc_span.md +++ b/doc/oc_span.md @@ -30,7 +30,7 @@ maybe(T) = T | undefined
add_link/2 Add a Link to the list of Links in the span.
add_time_event/2 Add an Annotation or MessageEvent to the list of TimeEvents in a span.
add_time_event/3
annotation/2 -Create an Annotation.
finish_span/1 +Create an Annotation.
finish_span/2 Finish a span, setting the end_time and sending to the reporter.
link/4 Create a Link which can be added to a Span.
message_event/4 Create a MessageEvent.
put_attribute/3 @@ -85,12 +85,12 @@ annotation(Description, Attributes) -> Annotation Create an Annotation. - + -### finish_span/1 ### +### finish_span/2 ### 

-finish_span(Span::maybe(opencensus:span())) -> true
+finish_span(Span_ctx::opencensus:span_ctx(), Span::maybe(opencensus:span())) -> true

diff --git a/doc/oc_trace.md b/doc/oc_trace.md index 681a7e3..3554bc0 100644 --- a/doc/oc_trace.md +++ b/doc/oc_trace.md @@ -116,7 +116,7 @@ Return the current span context in a `Ctx` or `undefined`. ### finish_span/1 ### 

-finish_span(Span_ctx::maybe(opencensus:span_ctx())) -> boolean()
+finish_span(SpanCtx::maybe(opencensus:span_ctx())) -> boolean()

@@ -220,7 +220,7 @@ Set Status. Returns true if the data was successfully updated. start_span(Name, SpanCtx) -> SpanCtx - + Create a new span, detached from any context. @@ -232,7 +232,7 @@ Create a new span, detached from any context. start_span(Name, SpanCtx, Options) -> SpanCtx - + diff --git a/doc/opencensus.md b/doc/opencensus.md index cc4f184..d79099c 100644 --- a/doc/opencensus.md +++ b/doc/opencensus.md @@ -99,7 +99,7 @@ message_event_type() = TYPE_UNSPECIFIED | SENT | RECEIVED 

-span() = #span{name = unicode:unicode_binary(), trace_id = opencensus:trace_id() | undefined, span_id = opencensus:span_id() | undefined, parent_span_id = opencensus:span_id() | undefined, trace_options = integer() | undefined, kind = opencensus:span_kind(), start_time = wts:timestamp(), end_time = wts:timestamp() | undefined, attributes = opencensus:attributes(), stack_trace = opencensus:stack_trace() | undefined, links = opencensus:links(), time_events = opencensus:time_events(), status = opencensus:status() | undefined, same_process_as_parent_span = boolean() | undefined, child_span_count = integer() | undefined}
+span() = #span{name = unicode:unicode_binary(), trace_id = opencensus:trace_id() | undefined, span_id = opencensus:span_id() | undefined, parent_span_id = opencensus:span_id() | undefined, tracestate = opencensus:tracestate() | undefined, trace_options = integer() | undefined, kind = opencensus:span_kind(), start_time = wts:timestamp(), end_time = wts:timestamp() | undefined, attributes = opencensus:attributes(), stack_trace = opencensus:stack_trace() | undefined, links = opencensus:links(), time_events = opencensus:time_events(), status = opencensus:status() | undefined, same_process_as_parent_span = boolean() | undefined, child_span_count = integer() | undefined}
@@ -109,7 +109,7 @@ span() = #span{name = unicode:unicode_b 

-span_ctx() = #span_ctx{trace_id = opencensus:trace_id() | undefined, span_id = opencensus:span_id() | undefined, trace_options = integer() | undefined}
+span_ctx() = #span_ctx{trace_id = opencensus:trace_id() | undefined, span_id = opencensus:span_id() | undefined, trace_options = integer() | undefined, tracestate = opencensus:tracestate() | undefined}
@@ -172,6 +172,16 @@ time_events() = [{wts:timestamp(), tracestate() ### + + +

+tracestate() = #tracestate{entries = [{unicode:latin1_chardata(), unicode:latin1_chardata()}]}
+
+ ## Function Index ## diff --git a/rebar.lock b/rebar.lock index 86787b4..0897ddb 100644 --- a/rebar.lock +++ b/rebar.lock @@ -1,4 +1,4 @@ -{"1.1.0", +{"1.2.0", [{<<"counters">>,{pkg,<<"counters">>,<<"0.2.1">>},0}, {<<"ctx">>,{pkg,<<"ctx">>,<<"0.5.0">>},0}, {<<"rfc3339">>,{pkg,<<"rfc3339">>,<<"0.9.0">>},1}, @@ -8,5 +8,10 @@ {<<"counters">>, <<"AA3D97E88F92573488987193D0F48EFCE0F3B2CD1443BF4EE760BC7F99322F0C">>}, {<<"ctx">>, <<"78E0F16712E12D707A7F34277381B8E193D7C71EAA24D37330DC02477C09EDA5">>}, {<<"rfc3339">>, <<"2075653DC9407541C84B1E15F8BDA2ABE95FB17C9694025E079583F2D19C1060">>}, - {<<"wts">>, <<"5CDF22C775CB1EBAE24C326A5DB6074D753C42F4BD12A9AA47CC62D3E2C71AD1">>}]} + {<<"wts">>, <<"5CDF22C775CB1EBAE24C326A5DB6074D753C42F4BD12A9AA47CC62D3E2C71AD1">>}]}, +{pkg_hash_ext,[ + {<<"counters">>, <<"A020C714992F7DB89178D27E1F39909E5D77DA3B80DAA4D6015877ED0C94B8AB">>}, + {<<"ctx">>, <<"52554D80F9D93B3F82DBA8E1776E8EA87B0D6218AE94BA0F73D61AD1579AED08">>}, + {<<"rfc3339">>, <<"182314DE35C9F4180B22EB5F22916D8D7A799C1109A060C752970273A9332AD6">>}, + {<<"wts">>, <<"97E2C65F17BCD488FCBE0B7073296FEE7A6AFCFA837C8ED10FB15E65A8713F02">>}]} ]. diff --git a/src/oc_reporter.erl b/src/oc_reporter.erl index cb49bf8..857d0f3 100644 --- a/src/oc_reporter.erl +++ b/src/oc_reporter.erl @@ -63,7 +63,7 @@ start_link() -> gen_server:start_link({local, ?MODULE}, ?MODULE, [], []). %% @doc -%% @equiv register(Reporter, []). +%% @equiv register(Reporter, []) %% @end register(Reporter) -> register(Reporter, []).