Sometimes I'm looking for a specific string inside the docs like a configuration flag. It'll be useful to be able to search for it somehow without having to dig through every page.

Singe we now create downloadable binaries on GitHub releases, we can re-enable the Download button on the home page:

We can either point it directly to GitHub releases, or better to a new Download page that will add a bit of explanation, like mention that Docker and binaries are the two alternatives.

cc @PikBot

License information is currently not present in the README.

I think it's worth to add a button Live Demo next to Get Started so people can quickly try Jaeger.

Because the live demo requires more information - the button could point to a new page "Live demo" with brief instructions and a link to hotrod blog post. Or we could embed the blog post directly on the page. The page could also contain information on how to configure tracer to send data to this instance.

Related issue: jaegertracing/jaeger#743

e.g.

• the usual process signals like CPU/memory usage, file descriptors, network usage
• Go runtime signals like goroutine count, GC
• Jaeger internals: dropped span count, mem queue size, storage write counts/latencies

Related commit: f456e2b

The June newsletter isn't published yet, but once it is, the website needs changing.

When I ran the setup step, npm install was successful, but make dev later failed because my default Node version was incompatible. We can add a check to the Makefile similar to this one:

https://github.com/jaegertracing/jaeger-client-node/blob/master/Makefile#L30

cc @lucperkins

Requirement - what kind of business use case are you trying to solve?

Contribute a change to the docs.

Problem - what in Jaeger blocks you from solving the requirement?

Running into an error when attempting to build the docs.

Note: I'm running hugo version 0.46.

When I run make develop I get the following error:

make develop
hugo server \
        --buildDrafts \
        --buildFuture \
        --disableFastRender \
        --ignoreCache
Building sites … ERROR 2018/08/07 21:24:15 error: failed to transform resource: SCSS processing failed: file "/Users/edwardfarro/dev/jaeger-docs/themes/jaeger-docs/assets/sass/variables.sass", line 15, col 1: File to import not found or unreadable: ../../node_modules/bulma/sass/utilities/initial-variables.
Total in 36 ms
Error: Error building site: logged 1 error(s)
make: *** [develop] Error 255

Looks like the sass is referring to files that were available before switching to the hugo asset pipeline, see line 2 and 10, below.

Proposal - what do you suggest to solve the problem or improve the existing situation?

Include the assets as a vendored resource.

Any open questions to address

N/A

This page is showing the old screenshot (error spans are no longer highlighted with pink background).

https://www.jaegertracing.io/docs/#trace-detail-view

cc @PikBot

Requirement - what kind of business use case are you trying to solve?

Use the new Kafka storage.

Problem - what in Jaeger blocks you from solving the requirement?

Lack of documentation about it.

Proposal - what do you suggest to solve the problem or improve the existing situation?

Document it:

• How to start the components (standalone/query/collector) with the new storage
• What configuration options there are
• Gotchas (write-only!)
• Bonus points: how to start Kafka for development purposes (Docker?)
• Missing bits (the component that ingests data and writes to Cassandra/Elasticsearch)

My Mac screen is set to approx. 70% brightness and the hyperlinks are a bit difficult to read because they are in light blue color that doesn't have enough contrast with the white background. Is there another color we could use?

cc @tiffon @lucperkins

• the order of upgrades of backend components is always: query, collector, agents
• compatibility guarantee between backend components: V-1 and V only
• compatibility between clients and backends: by default backend should be compatible with all clients, but there may be future exceptions

This is just my preference, but I feel the current style for inline code fragments (grey background and magenta color) is too strong / distracting. It's especially evident on the client-features page where it introduces colors in the Feature column when it's not really needed. I've been experimenting with removing the color & bg on different pages, e.g.

vs.

This is just for inline fragments, the code blocks using magenta are fine.

@lucperkins when making the screen a bit smaller, the feature matrix table overlaps with the right side menu, as below, until the next @media breaking point when the right sidebar disappears.

I was actually thinking if perhaps it makes sense to move the feature matrix to a separate page and give it an altered layout template that doesn't have the right sidebar at all, because the table is best viewed when it has more horizontal space.

Jaeger collectors/clients emit metrics about the health of the system but they aren't documented anywhere. By documenting them, new users can see which metrics to look out for when setting up jaeger.

Starting from 1.6, the Docker images for Jaeger have been changed so that the binary is the entrypoint, effectively causing more specialized usage to break. For instance:

$ docker run --rm \
    -e SPAN_STORAGE_TYPE=cassandra \
    jaegertracing/jaeger-collector \
    /go/bin/collector-linux help

Source: https://www.jaegertracing.io/docs/deployment/#configuration-options

Should be changed to read:

docker run --rm \
    -e SPAN_STORAGE_TYPE=cassandra \
    jaegertracing/jaeger-collector:1.6 \
    help

This ticket is about reviewing all the Docker commands used in the documentation and:

1. Pin the images to 1.6 -- we'll then to manually pin to newer versions in the future, which will "force" us to review each command. Bonus points: the commands won't break if we just release a breaking change and "forget" to change the docs
2. Remove the /go/bin/...-linux part of the docker run command

Well, I spent a few hours scratching my head on why my type:const was not being honored in the strategies.json file. Then I dug into the code and saw it was because it isn't supported. The Sampling page in the docs lists it as valid, but there is one line at the very bottom that just says 'ratelimiting' and 'probabilistic' are supported. Would have saved me some frustration if this was more explicit.

However, I did learn more about the project by digging into the source code..so win-win?

e.g. here:

docker run -d -e \
+  COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
+  -p 5775:5775/udp \
+  -p 6831:6831/udp \
+  -p 6832:6832/udp \
+  -p 5778:5778 \
+  -p 16686:16686 \
+  -p 14268:14268 \
+  -p 9411:9411 \
+  jaegertracing/all-in-one:latest

Why do we recommend that instead of just running on host network?

@pavolloffay @jpkrohling

Is it possible to version the documentation? ie if we add a new feature and update the documentation, some newer users might think that the feature is compatible with all existing versions and become confused when it doesn't work as documented.

what are the viable approaches? Do we manually write in the documentation, from version 1.3.0 onwards etc. or are there more sophisticated ways of doing this?

The website needs to have a clear message regarding how to provide feedback (as bug reports or enhancements). It could be as simple as "report bug reports by opening issues against the jaegertracing/jaeger repository".

• show how to whitelist baggage
• set maximum length

https://www.jaegertracing.io/docs/client-features/

I think we need:

• a row "128bit Trace ID" under "Inter-process propagation wire format (headers)" section (only Go, C#, and C++ clients support it today - jaegertracing/jaeger#858)
• a row under Environment Variables for JAEGER_TRACEID_128BIT, which afaik is only supported by the C# client at the moment (jaegertracing/jaeger-client-csharp#94)

cc @PikBot

Add this documentation to: http://jaeger.readthedocs.io/en/latest/client_libraries/

Each client (Java, Go, possibly others) stores internal metrics, like the number of spans sampled, traces submitted, and so on.

For the Java client, the following issue can be used as a base for this documentation: jaegertracing/jaeger-client-java#350

cc @objectiser , @JStickler

how to install jaeger without docker on linux?
I can't find cassandra sql file, and collector config file and standalone 、query service's config file.

For example, Client Features should really be just a sub-menu under Client Libraries, not the top-level entry.

Every month, we try to publish a newsletter. It would be nice to have the website automatically updated with the latest one whenever it's published.

https://www.jaegertracing.io/docs/sampling/

(a) change "Collector Sampling Configuration" section title to "Collector Configuration", looks better in the TOC in the right sidebar

(b) explain mounting config file for Docker. From gitter

maniaabdi @maniaabdi 16:19
Hello everyone, how should we specify sampling strategies to jaeger-collector. I am using the following command
sudo docker run --rm -p14268:14268 -p9411:9411 -p14267:14267 -e CASSANDRA_SERVERS=192.168.100.15 -e CASSANDRA_PORT=9042 jaegertracing/jaeger-collector --sampling.strategies-file=/home/ubuntu/strategies.json
and I keep getting
{"level":"fatal","ts":1534364309.442946,"caller":"collector/main.go:228","msg":"Failed to create sampling strategy store","error":"Failed to open strategies file: open /home/ubuntu/strategies.json: no such file or directory","errorVerbose":"open /home/ubuntu/strategies.json: no such file or directory\nFailed to open strategies
but I am sure that my file exist
any help is really appreciated

Won Jun Jang @black-adder 16:26
https://stackoverflow.com/questions/41092587/passing-file-as-argument-to-docker-container
you have to pass the file to the container as a volume

Prithvi Raj @vprithvi 16:26
(because the file isn't in the container)

Won Jun Jang @black-adder 16:26
-v /home/ubuntu/strategies.json:/home/ubuntu/strategies.json should work

A nice to have feature - when we used mkdocs the TOC in the right sidebar would automatically highlight the current section header based on the page vertical scroll position.

Moved from jaegertracing/jaeger#384

Problem

Jaeger already has 6 official client libraries, with different levels of support for different features. Ideally we want to standardize on a uniform set of features across all languages, but in practice some libs will be lagging behind others, so it would be good to have a feature matrix in the documentation.

Proposal

Define feature matrix in a YAML file data/clients.yaml like this:

features:
  - name: udp_jaeger_thrift
    description: Report spans in `jaeger.thrift` format over UDP
  - name: propagation_b3
    description: Support Zipkin's B3 headers as wire format for span context

clients:
  - name: Go
    repo: http://github.com/jaegertracing/jaeger-client-go
    features:
      udp_jaeger_thrift: Y
      propagation_b3: partial
  - name: Java
    repo: http://github.com/jaegertracing/jaeger-client-java
    features:
      udp_jaeger_thrift: Y
      propagation_b3: N

Ideally, the values in the fields like description (or all fields) would support Markdown.

Open questions

• can the template for rendering the table be written directly in clients.md?
• if not, where do we define the template and how can we inline it in clients.md?

@lucperkins appreciate your input

There is white space in the header between "Blog" and GitHub logo that links to https://medium.com/jaegertracing (in the website header). Should a Medium logo be added there?

At the moment, there is no page-level metadata for OpenGraph, Twitter Cards, etc. enabled for the site. In order to be properly discoverable in search results, embeddable in tweets and Facebook posts, etc., this will need to change.

@yurishkuro I feel like this issue should be resolved before the DNS switch for jaegertracing.io.

it could use an update

The existing documentation on readthedocs has probably accumulated many inbound links over time, so we don't want to simply shut it down. But we don't want to let it run a stale copy either. The best solution would be to redirect from all existing pages to the new site.

Unfortunately, the User Redirects feature of ReadTheDocs only seems to support internal redirects. The Domains tab in the admin console says "This allows you to add domains to your project. This allows them to live in the same namespace in the URLConf for a subdomain or CNAME." I added jaegertracing.netlify.com, but so far no impact.

There are also a couple of tricks people are suggesting on SO, one with javascript.

There's also an issue mkdocs/mkdocs#1102 in mkdocs to support redirects, but I don't see a solution yet.

it only contains docs/monitoring.md which is a copy of content/docs/monitoring.md

cc @lucperkins

From a cncf member:

We've noticed that the project website (https://www.jaegertracing.io/) mentions Jaeger as "a Cloud Native Computing Foundation member project."

Please, update the wording to "We are a Cloud Native Computing Foundation hosted project.", which is a correct statement.

Using Chrome on Ubuntu. If I press ctrl-f at https://jaeger.readthedocs.io the cursor will end up in the top right search box. Naturally, I expect ctrl-f to give the Browser built in Find... function. To override this seems like an anti-pattern.

Pressing f will also give me the top right search box. This seems more reasonable.

Not sure I understand what framework is used for actually producing the web page from the markdown.

After a fresh checkout, make macos-setup resulted in the following error:

$ make macos-setup
brew switch hugo 0.37.1 && brew link --overwrite hugo
Error: hugo not found in the Cellar.
make: *** [macos-setup] Error 2

Seems like it expects Hugo to be installed, already.

make macos-setup finished without error when I ran it after installing hugo.

Reference: jaegertracing/jaeger#457

The website (index + all docs pages) needs to include a link to a new security page. This security page should advise users to send an encrypted message to the mailing list [email protected] using the PGP public key C043A4D2B3F2AC31. Something similar to https://qaclana.io/security/

Key:

-----BEGIN PGP PUBLIC KEY BLOCK-----
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
oF+qZY4uEvqFvYo8
=KQzT
-----END PGP PUBLIC KEY BLOCK-----

Link to the key on a public server: https://sks-keyservers.net/pks/lookup?op=get&search=0xC043A4D2B3F2AC31

Requirement - what kind of business use case are you trying to solve?

Redirect HTTP traffic to HTTPS

Problem - what in Jaeger blocks you from solving the requirement?

Newer versions of Chrome (other browsers to follow) will start displaying a "this website is not secure" warning soon for websites not using HTTPS.

Proposal - what do you suggest to solve the problem or improve the existing situation?

On Netlify control panel, there's an option like this under "Domain management" / "HTTPS":

See jaegertracing/jaeger-client-java#379

Page to remove the reference from: https://www.jaegertracing.io/docs/client-features/

Hi,
When I go to Features page in Docs in resolution 1366x768, the page displayed like this.

So I want to fix that by adding an css attribute into .page--docs .nav

And result:

I will create a pull request soon.

https://www.jaegertracing.io/docs/getting-started/#running

left is readthedocs, right is hugo.

left feels better, a zoom-ed in version of the logo, since the fine details are hardly legible in favicon

@lucperkins

E.g. https://medium.com/jaegertracing/april-2018-newsletter-bad00a68080e

For each of the following linked tasks, change the documentation to include them. Add also a deprecation note on the description for the old name:

• jaegertracing/jaeger-client-go#282
• jaegertracing/jaeger-client-java#521

I just went through an exercise of running Jaeger by running Cassandra, the collector, the agent, and the UI in separate docker containers following the instructions here: http://jaeger.readthedocs.io/en/latest/deployment/. Most of the needed information is there, although not in a way that would be clear to a novice, and there are also a few omissions.

Here are my suggestions:

1. The section order should change to be the same as the order you need to do things in, i.e. first start the storage backend, and then the collector, before starting the agent or ui. If the agent is started before the collector it will produce errors repeatedly at short, regular intervals.

2. For Cassandra, adding syntax for the docker command might be helpful. Also, I don't think this page points out that you need to clone source to get the create.sh script to create the keyspace.

3. For the collector, although the doc does say you need the --cassandra.keyspace and --cassandra.servers options, it never gives proper syntax for the command. I used "docker run -it --rm -p14267:14267 -p14268:14268  jaegertracing/jaeger-collector /go/bin/collector-linux --cassandra.keyspace=jaeger_v1_test --cassandra.servers=192.168.0.183"

I also found that if I didn't give the port options when I started the collector the agent couldn't connect to it. I'm not sure whether this was something I was doing, or if this needs to be added to the doc.

4. Agent. This command requires the --collector.host-port option, which also means it needs the longer form for the docker command (with /go/bin/agent-linux on the command line.) . The long form is specified in the "Discovery System Integration" section, but I found that a bit confusing, as it talks about multiple collectors behind a load balancer, and that's not something that I was doing, or someone who was trying to read the docs for the first time might be doing.

5. UI. An example docker command would be helpful. I did "docker run -it -p16686:16686 jaegertracing/jaeger-query:latest /go/bin/query-linux --cassandra.keyspace=jaeger_v1_test --cassandra.servers=192.168.0.183"

https://jaegertracing.io/ redirects to https://www.jaegertracing.io/ but tries to load assets from https://jaegertracing.io/

“https://jaegertracing.io/css/style.min.6614ad8ede1540eb1d3d6a8d174ef71da25924481de3146d202f9c45de92ef74.css” is not eligible for integrity checks since it’s neither CORS-enabled nor same-origin. www.jaegertracing.io
“https://jaegertracing.io/js/anchor.min.min.5b06633d479f6f474d5e06d60592e604cf6b3db88c864f05b76750e44ca1f695.js” is not eligible for integrity checks since it’s neither CORS-enabled nor same-origin. www.jaegertracing.io
“https://jaegertracing.io/js/jquery-ui-1.9.1.custom.min.min.cb717b0a621737a7ee7f37031ead116ce764a78404cfc5a6ebac8841a2f47550.js” is not eligible for integrity checks since it’s neither CORS-enabled nor same-origin. www.jaegertracing.io
“https://jaegertracing.io/js/jquery.tocify.min.min.c6b18911556f32cc9d302f867ed4f7cb2795ae28ca259510dbb0ee2d7fb9b56a.js” is not eligible for integrity checks since it’s neither CORS-enabled nor same-origin. www.jaegertracing.io
“https://jaegertracing.io/js/app.min.08e72cf2fb39acc815d203fb56f376881fb35572b82d6744e64d479d5974b9b2.js” is not eligible for integrity checks since it’s neither CORS-enabled nor same-origin. www.jaegertracing.io
“https://jaegertracing.io/js/anchor.min.min.5b06633d479f6f474d5e06d60592e604cf6b3db88c864f05b76750e44ca1f695.js” is not eligible for integrity checks since it’s neither CORS-enabled nor same-origin. www.jaegertracing.io 

the result looks like this: