census-instrumentation / opencensus-website

opencensus.io website content

Warning

OpenCensus and OpenTracing have merged to form OpenTelemetry, which serves as the next major version of OpenCensus and OpenTracing.

OpenTelemetry has now reached feature parity with OpenCensus, with tracing and metrics SDKs available in .NET, Golang, Java, NodeJS, and Python. All OpenCensus Github repositories, except census-instrumentation/opencensus-python, will be archived on July 31st, 2023. We encourage users to migrate to OpenTelemetry by this date.

To help you gradually migrate your instrumentation to OpenTelemetry, bridges are available in Java, Go, Python, and JS. Read the full blog post to learn more.

opencensus.io

This repo contains the source for the opencensus.io website.

Contributing

Contributions are highly appreciated! Please follow the steps below to contribute: Important to Note: This site is currently built on Hugo v0.31.1 found Here. Use v0.31.1 to run your edits locally.

1. Install Hugo.
2. Check out the website source:

$ git clone [email protected]:census-instrumentation/opencensus-website.git
$ cd opencensus-website

3. Make a change and run the website locally to see if it all looks good.

$ hugo

$ hugo serve

Started building sites ...

Built site for language en:
...
...
total in ms

Watching for changes in /Users/you/Desktop/opencensus-website/{content,layouts,static,themes}

Serving pages from memory

Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender

Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

Press Ctrl+C to stop

4. Go to http://localhost:1313/ to display the rendered website locally.
5. If it all looks good, create a pull request with the changes.
6. Once your PR is approved and merged, the website will be automatically regenerated and published.

opencensus-website's Issues

Guides and tutorials just pointing to GitHub

The footer of the website links to guides and tutorials. Those just link back to the GitHub org or the opencensus-proto repository.

Add Analytics

Add Google Analytics to the pages so we can see viewship.

Remove sc_* for each page

The current organization of the website requires a partial template for each new page.

New pages should be possible to add only by authoring a new markdown file.

Remove inline HTML

The reason we want to use hugo is not to use any HTML markdown in the content docs.

• Remove all {{% sc_ulist %}}
• Remove all  

Add LICENSE and AUTHORS

LICENSE and AUTHORS files are missing

Remove sc_code shortcode, instead use code HTML tag

Convert the static HTML site into a huge website

Instrumentation best practice guide.

One of he best thing about the Prometheus site was the Best Practices documentation. This gave relatively product agnostic best practice tips for instrumenting code. Some was prom specific, but much was just good advice.

https://prometheus.io/docs/practices/instrumentation/

Similar advice for tracing is hard to come by.

e.g.

• how many spans is too many?
• span naming, (is cardinality a problem? we hit issue in jaeger)
• usage of logs (I've attempted to have all app logs within spanned code mirrored into spans, is that a good idea?)
• usage of message events
• what's appropriate for tags
• what's appropriate for propagated tags (once supported).

I'd be happy to contribute, perhaps source and edit advise, but I definitely have not had sufficient experience to know what is good or useful (we are just beginning our tracing journey).

Remove vendor specific tutorials from the Overview

Vendor specific tutorials should be in listed in the blog or or under /docs. Remove them from the left navigation on overview and language pages.

Fix inline linking

All the links such as (../tags/index.html) should be just (/tags).

Link to Go GitHub readme for now

While we are trying to fix the language-specific quickstarts, we should link to https://github.com/census-instrumentation/opencensus-go instead of keep the Go-specific page around.

Our users already repeatedly said that https://opencensus.io/go/index.html was not very helpful for them but our repo README was.

Don't use all caps in the content

There is content with ALL CAPS in the source.

If all caps is a style choice for titles, it should be applied by using CSS.

text-transform: uppercase;

Cache firebase-tools and hugo on Travis

Our CI deployment would be significantly faster if these dependencies are cached.

Get content for opencensus-website/content/go.md from opencensus-go README

opencensus-website/content/go.md looks like an out-of-date copy of the opencensus-go README.md.

Can we make the build system for the website import this from opencensus-go latest released version automatically?

Add a link to the GitHub organization on the top navigation

I have seen several of our contributors having hard time recognizing the octocat on the right. It might be useful to add a GitHub text link to the top navigation.

Fix the license on the footer

The footer says "Copyright © OpenCensus 2018 | All Rights Reserved." but this is misleading.

The license is Apache 2 and should be attributed to the "OpenCensus Authors".

Add site URL to GitHub org page

There is a setting for that, and the project website should be linked on top-level, too.

Name partials better

There is a partial named sc_gloss1 even though there is no sc_gloss2.

Rename this to sc_gloss.

Generation is broken

When I try to regenerate files, this is what I see:

hugo
Started building sites ...
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_guides" in page "guides.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_trace" in page "trace.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_spanner" in page "spanner.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_gogrpc" in page "gogrpc.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_tags" in page "tags.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_stats" in page "stats.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_reference" in page "reference.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_quickstart" in page "quickstart.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_community" in page "community.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_overview" in page "overview.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_index1" in page "index.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_ruby" in page "ruby.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_python" in page "python.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_php" in page "php.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_java" in page "java.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_erlang" in page "erlang.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_go" in page "go.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_cpp" in page "cpp.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_glossary" in page "glossary.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_docs" in page "docs.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_roadmap" in page "roadmap.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_blog" in page "blog.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_faq" in page "faq.md"
ERROR 2018/06/18 16:12:29 Unable to locate template for shortcode "sc_about" in page "about.md"
Built site for language en:
0 draft content
0 future content
0 expired content
24 regular pages created
14 other pages created
0 non-page files copied
0 paginator pages created
2 categories created
2 tags created
total in 24 ms

I cannot regenerate the website.

Support HTTPS

https://opencensus.io/ is failing with a certificate error. We need to support and probably default to HTTPS.

Remove /reference and /quickstarts

These index pages are not adding anything to the /docs page. Let's have a single canonical index for all the docs.

Amazon X-RAY roadmap.md

WRT https://opencensus.io/roadmap/

I thought there was at least golang support for amazon X-ray ?

Emmanuel Odeke from Orijtech Gave his talk Planet-Scale Observability – Distributed Tracing and Monitoring with OpenCensus at https://www.meetup.com/golangsf/events/249471121/

Don't use target=_blank

It is not good practice to set a _blank target. We should always honor user's preferences. Users know how to open in a new tab if required.

Revise the Go quickstart

This is a tracking bug for the work required for #158.

Titles should be just an h1

Each page has this gigantic title section:

<section class="sections lang" id="lang">            
	<div class="container">
		<div class="row">   
			<!-- GLOSSARY CONTENT START -->
			<div class="title">

				<!-- CENTER COULMN -->
				<div class="col-md-12 box" style="margin:0px 24px 0px 5px;">
				<h1>Cloud Spanner</h1>
					{{.Inner}}
			   </div>
				<!-- END CENTER COULMN -->
				<!-- GLOSSARY CONTENT END -->
			</div>
		</div>
	</div>
</section>

Titles should be authored only by authoring a h1.

# Cloud Spanner

Remove irrelevant link

On the entry point of the website, https://opencensus.io/overview/index.html, the top link says

"HERE IS A GREAT ARTICLE THAT EXPLAINS TRACING CONCEPTS"

This is so irrelevant here and needs to be added to the blog page. Please remove this link from this page.

Remove unmaintained community links

We have a Facebook page and a Google+ account that are not maintained. Remove the links to both.

Try to have a single footer

There is an index footer and a regular footer. Each time a link needs to be updated, it requires two changes. This approach is error-prone. Remove the requirement for having two footers.

Use high quality logos of the partners/integrations

On the homepage, the partners section feature a low quality set of logos. Replace them with higher quality logos.

Follow header order

Content contains a mix of different header levels and some headers are only represented as bold text.

Follow the following order:

# h1
## h2
### h3
#### h4

Add new article to the blog

Monitoring HTTP Latency with OpenCensus and Stackdriver
https://medium.com/google-cloud/monitoring-http-latency-with-opencensus-and-stackdriver-bf561608e81a

As a note, can we make publishing new content to the blog page a little bit easier? It requires readjustment of the table for each new item. Replacing the table with floating divs can improve this problem.

sticky tab is large and creates cut-off/invalid image on index page

I just took a look at the OpenCensus website and saw this

Seems like the top sticky tap was expanded a whole lot hence the scrollable area is smaller thus the underbite

Templates live in two different places

One set of templates are under /layouts
The other set of templates are under /themes/census/layouts

Unify them.

How do I integrate links goes to C++ repo

See the How do I integrate question at /faq. Remove this until we have a proper answer.

Remove guides.md

This page doesn't contain any links and guides should be linked from /docs. We don't need a new page for this.

Optimize whitespace; font size, weight and kerning

Several of our users gave feedback that the font is not easy to read. Search for best practices for this font in terms of size, weight and kerning.

The other feedback was the unproportional spacing between some items. Revise/review whitespace all across the site.

Remove CNAME

This file was required by GitHub pages, we can remove it now.

Please add/fix RSS feed

Hi

I follow a gazillion tech blogs in an RSS reader (I use Feedly). I can't add the opencensus blog to feedly, it doesn't pick up any rss feeds. I think a lot of technies use rss feeds - please consider adding/fixing this. Thanks!

Remove the accordion on FAQ

This is a fancy addition but making it hard to read the page. This is a developer facing website, our visitors just want to quickly search and skim information.

Pages not working locally with hugo 0.32

I run the following:

$ hugo serve

Then, it starts the web server and serves the homepage. From the homepage, when I click on the links, there are all 404s. For example,

$ curl http://localhost:1313/quickstart/
404 page not found

index.html: fix typo "HOW IS BEHIND OPENCENSUS"

Reported offline by @imavroukakis on Twitter https://twitter.com/chaosaltar/status/1004244460539121664
we've got a typo from a recent change (a day ago #69)

Remove the necessity to add a new partial for each page

There is a partial for each page, e.g. sc_blog, sc_cpp, sc_index1...

This is not a scalable approach. Modify the design not to require additional partials to have a new page.

We should never ever maintain this much of HTML to serve a low-impact site like OpenCensus.

Fix wrong definition of tags in glossary

Tags are to provide dimension to the collected data and propagate the dimension, not to store information.

See the section where it says:

Tags are key-value pairs that are used to store information about metrics for example;

Try to have a single nav.html

Similar to #115, it is error prone to having to update two navigation headers.

Provide best practices for metric instrumentation

Currently there does not seem to be comprehensive reference documentation on how to use OpenCensus. The language specific guides do not seem enough to cover this.

Packages like ochttp give away hints that there's such a thing as namespacing by domain names and / separated paths. But rules on how to use them are missing. In particular the example on a custom metrics just uses a flat view name, which causes some confusion.
For example, what's new to me (compared to Prometheus) is inclusion of available tags into the name (..._by_hostpath), which raises some questions I'd need guidance on. I'd generally expect http metrics to have status, method, path, and possibly host. Would my metric then be http_requests_by_hostpathmethodstatus, http_requests_by_host_path_method_status or similar?

Similarly, information on recommended usage of tags and their cardinality seems very important.

Based on past experience, people will not get those things right by default and it can take years for initial mistakes to get fixed and rolled out. There's probably no single right way, which makes it even more important to come up with best practices early on so people experience as much consistency as possible across systems.

I mostly ran into this w.r.t metrics, but the same probably applies for traces.

For inspiration/reference, this is the relevant Prometheus documentation:

• https://prometheus.io/docs/practices/naming/
• https://prometheus.io/docs/practices/instrumentation/

Categorize glossary

Glossary is randomly ordered. Categorize it by topic or sort it alphabetically.

Fix misleading answer on FAQ

It says

OpenCensus provides a stand-alone application that uses a gRPC channel to communicate with the OpenCensus code linked into your application. The application displays configuration parameters and trace information in real time held in the OpenCensus library.

although z-pages are not standalone binaries, they are handlers provided by the same binary.

Provide definitions of terms

It would help tremendously to define what a trace, a span, a measurement, view, aggregation, stat, and any other technical terms mean. I think most people have a sense, but putting it on paper would clear up a lot of confusion.

Proposal: Revise the language quickstarts

Our language specific quickstarts are currently not optimal.

• We would like to encourage the use of framework integrations first.
• Then, show a few examples of how to add custom instrumentation.
• We also want to demonstrate how to register an exporter and a screenshot from the backend, so the user understand how things work end to end.

I'd like to address these issues by pivoting a new quickstart structure with the Go quickstart. We will then apply similar modifications to the rest of the pages.

Tracking bugs

• Go: #159
• C++
• Erlang
• Java
• PHP
• Python
• Ruby

Remove the expanding menu on the about page

There is only a paragraph of text on the about page but it requires user to expand it. Remove this requirement.