census-instrumentation / opencensus-website Goto Github PK

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

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

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

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

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.

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

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

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;

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

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?

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

Rename this to sc_gloss.

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).

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.

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/

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;

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

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

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.

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.

LICENSE and AUTHORS files are missing

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

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.

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

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.

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

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

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

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

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

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)

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

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

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.

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".

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.

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

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!

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.

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

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.

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

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

Unify them.

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.

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/

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

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.

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

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.

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.