content: add C++ exporter guides and how to create a custom exporter

[odeke-em]

We've gotten interest from an influential C++ project that would like to instrument their backend.

This issue is a placeholder to add content to the website for C++

[odeke-em]

Alright, and the good news is in, I was able to get the gracious @g-easy to write for us a completely runnable/standalone end-to-end program that doesn't require forking OpenCensus-CPP nor having to tame the beast called Bazel. His guide is at https://docs.google.com/document/d/14GGmrltkXelSPMe585jncFsLavde2Xz-mPXchnJRknE/edit?usp=sharing

or copy+paste from his doc

How to start an OpenCensus C++ Project
@g-easy, 2018-09-12 (US TZ)

We rely on bazel as a build system and the Abseil libraries.

To start, make a new directory and add a file called WORKSPACE. bazel needs this file at the root of your project.

In the WORKSPACE file, pull in OpenCensus and its dependency, Abseil:

-=-
http_archive(
    name = "io_opencensus_cpp",
    strip_prefix = "opencensus-cpp-master",
    urls = ["https://github.com/census-instrumentation/opencensus-cpp/archive/master.zip"],
)

# OpenCensus depends on Abseil so we have to explicitly pull it in.
# This is how diamond dependencies are prevented.
http_archive(
    name = "com_google_absl",
    strip_prefix = "abseil-cpp-master",
    urls = ["https://github.com/abseil/abseil-cpp/archive/master.zip"],
)
-=-

http_archive tells bazel to configure an "external repository" by downloading an archive via http, unpacking it, and removing the top-level directory (strip_prefix)

Next, add a C++ file, e.g. helloworld.cc:

-=-
#include "absl/time/clock.h"
#include "absl/time/time.h"
#include "opencensus/exporters/trace/stdout/stdout_exporter.h"
#include "opencensus/trace/sampler.h"
#include "opencensus/trace/span.h"

int main(int argc, char **argv) {
  // Register stdout exporter. This will write span data to stdout for testing.
  opencensus::exporters::trace::StdoutExporter::Register();

  // Samplers are potentially expensive to construct. Use one long-lived sampler
  // instead of constructing one for every Span.
  static opencensus::trace::AlwaysSampler sampler;

  // Done initializing. Make a Span:
  auto span = opencensus::trace::Span::StartSpan("example.org/DoWork", nullptr,
                                                 {&sampler});
  span.AddAnnotation("Starting work.");
  // Sleep for [1,10] milliseconds to fake work.
  absl::SleepFor(absl::Milliseconds(rand() % 10 + 1));
  span.AddAnnotation("Finished work.");
  span.End();  // Spans must be Ended explicitly.

  std::cout << "Waiting 10.1s for exporters to run...\n\n";
  absl::SleepFor(absl::Milliseconds(10100));
}
-=-

Next, add a BUILD file:

-=-
cc_binary(
    name = "helloworld",
    srcs = ["helloworld.cc"],
    linkopts = ["-pthread"],
    deps = [
        "@com_google_absl//absl/time",
        "@io_opencensus_cpp//opencensus/exporters/trace/stdout:stdout_exporter",
        "@io_opencensus_cpp//opencensus/trace:trace",
    ],
)
-=-

"deps" is a list of libraries that our binary depends on. As well as linking these libarier, bazel will also make their headers available to the compiler.

"@io_opencensus_cpp" refers to an external subrepository.
"//opencensus/trace" is a directory path within that subrepository.
And ":trace" is the name of a cc_library target in that directory. (TODO: add link to file and line in github showing cc_library)

From the compiler's point of view, all of the sources and dependencies' headers are merged into a single hierarchy, e.g.:

helloworld.cc
absl/time/time.h
opencensus/trace/span.h

This explains the #include paths above.

Finally, build the binary:

-=-
bazel build :helloworld
-=-

The first time it's run, bazel will download and unpack the http_archives.

The binary will be produced at bazel-bin/helloworld

With these I think we have enough material to make the C++ quickstarts. /cc @PikBot @hvent90

[odeke-em]

Alright, so the quickstarts are done and shipped:

• [X] Tracing https://opencensus.io/quickstart/cpp/tracing/
• [X] Metrics https://opencensus.io/quickstart/cpp/metrics/

[g-easy]

Is this issue done?

[odeke-em]

Not yet @g-easy, we still need to write:

• Guide for creating a custom stats exporter in C++
• Document the various trace and stats exporters in C++