search

jaegertracing / documentation

Documentation/website for the Jaeger Distributed Tracing project.
https://jaegertracing.io/
Apache License 2.0
67 stars 161 forks source link

Jaeger Deployment doc page needs revision #179

Open kevinearls opened 7 years ago

kevinearls commented 7 years ago

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.

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

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

jpkrohling commented 7 years ago

Possibly related: https://github.com/jaegertracing/jaeger/issues/468#issuecomment-336118121 https://github.com/jaegertracing/jaeger/issues/466#issuecomment-335746564

That said, docs are going to be overhauled.

ideepika commented 7 years ago

I Tried adding the changes that were highlighted , could these helpful

yurishkuro commented 7 years ago

@kevinearls no objections to changing/extending the docs, but I don't think we should be recommending overriding command line switches in Docker commands, they all have equivalent env variables.

kevinearls commented 7 years ago

@yurishkuro I agree, but are those documented anywhere? To get the equivalent environment variables do I just take the options output by --help, change them to all caps, and change periods and dashes to underscores?

yurishkuro commented 7 years ago

Yes

yurishkuro commented 5 years ago

@kevinearls @jpkrohling is this still an issue?

kevinearls commented 5 years ago

@yurishkuro not for me, I'm no longer at Red Hat so I'm not working on this anymore.

jpkrohling commented 5 years ago

Sorry, I wanted to review the doc before commenting but got busy with other issues. I'll try to take a look at this one today, but I think it might not be a problem anymore, as I believe we would have heard more complains.