Provide sample configurations that include both Jaeger and a demo app

[yurishkuro]

We are getting a LOT of questions about various docker-compose or k8s setups not working, that usually manifest in "I do not see traces in Jaeger UI". In most cases it is due to user's mistake in the configuration. It would be good to provide working sample configurations that include not just the Jaeger backend components, but also a demo application, e.g. HotRod, so that people can use those configurations as a starting point, and if their own application doesn't work afterwords they can check what is different from the sample config. Preferably, these configurations should be tested in CI, e.g. by executing a request against HotRod app and then querying Jaeger UI for a trace.

[jpkrohling]

Perhaps we could start with a blog post, evolving it later to a page in the documentation, similar to what we did with the troubleshooting guide?

[pavolloffay]

Isn't the troubleshooting guide already trying to solve this?

We should reiterate on it add it directly on the docs.

[jpkrohling]

It kinda is, but it completely ignores Kubernetes. If the amount of questions specific to Kubernetes is increasing, it might be worth having dedicated instructions for that env.

[pavolloffay]

A good comment from gitter:

I am debugging why my service is not sending any traces. I have configured a HTTP endpoint as the collector. Is there a POST I can make to the collector to test that the collector is indeed getting data.

I think we should move parts of that blog post into our docs and make it generic enough so people understand how jaeger works and can debug it on any environment.

[TomBalt]

Step by step config for remote sampling would be appreciated as well. Cause now, is really unclear how to do it.

[sagaranand015]

hey guys,
So, as per the original description by @yurishkuro , the ask is basically to provide a basic k8s/docker-compose configuration files for all/any Jaeger Components. In addition, have a demo app that works with this setup out of the box, with minimal(or none) changes for anyone starting with Jaeger. Can this be validated please?

Assuming the above, one approach can be to create a samples repository within the JaegerTracing organisation and have separate branches within this repo to cater to a particular kind of configuration + a demo application.
For Example,

1. Say, a user needs a basic Cassandra backed collector and query components (only) and a demo application configured to send trace data to this collector, which can then be viewed in the UI. This can be supplemented by a README for this scenario.
2. Similarly to [1], a use case can be to just send trace data to an in-memory collector from a pre-configured demo application.
3. The same approach can be extended to include advanced uses case, demoing SpanContext(and others) and its propagation across microservices and in the Jaeger UI.

Going by this use-case approach allows for community contributions of k8s/docker-compose setups and demo applications ranging from very basic to extremely advanced use cases of Distributed Tracing.

Having said this, I do see the problem of branch management within a single repository as the samples grow. Any better ways of managing code, while sticking to the use-case approach?

I do have a few setups on k8s that I've been trying with, along with demo applications in both Java and golang. If we're able to discuss more and refine the approach on this, I think this will be a good way to get a lot of Jaeger usage samples out.

Thanks

[yurishkuro]

@sagaranand015 there is no need to deal with branches, just have different directories for different samples. We already have /examples dir in the main repo. That is not the challenge. The challenge is making sure that the samples are actually working, which is why the preference is to have them tested via CI. For example, there is a docker-compose file for HotROD + all-in-one combination, but it's only been tested manually.

Having said that, just having more examples, even if not CI-tested, would still be useful, with the hope that if those examples are not working as is people would ask to fix them.

[sagaranand015]

Thank you for the input @yurishkuro . So, a couple of questions:

1. Can we start with a basic app(first java and then golang) with a README (as a tutorial) with different versions of how to use Jaeger Components? (Eg.: running just a binary, having a docker-compose yaml, having a kubernetes sample yaml etc.)

2. These examples can be CI tested but lets proceed with [1] in the first phase. Does that work?

[yurishkuro]

Well, I think readme is really not helpful, we need examples of the actual runnable configurations. Readme can describe how to run them.

What kinds of Java app are you thinking of? That's an additional dimension of complexity, I would rather stick with something simpler like the HotRod app.

[yurishkuro]

NB: there is a docker-compose file for running HotROD (added in #1579)

[Amiedeep]

Hi Guys,

I just came across this issue and might help with a similar setup. I have been experimenting with Jaeger and created a repository for the demo purposes within my organization. This demo has two services written in Golang, and Java (Spring boot), communicating with databases (Postgres, Redis), and sending tracing data to Jaeger. All of the setup can be run on local, minikube, and kubernetes cluster using the helm chart provided.

I am happy to make more changes as suggested and can write a blog. Let me know if this helps and we can include this repo in the examples folder.

[yurishkuro]

@Amiedeep thanks for the offer! I think including Java code in the Jaeger repo (all Go) would not be ideal. The point of this ticket is not to create a new application (we can still use HotROD, that's already enough code to maintain), but to create a deployable & CI-tested configuration.

[Amiedeep]

Thank you for the clarification @yurishkuro; Make sense to me.

[fktkrt]

My earlier PR was introducing a similar simple docker-compose setup, but with Grafana, Loki and Prometheus involved: #2408
I can break these into separate pieces and provide instructions for the deployments.

Not sure if it's a good idea, but would a separate repository for the examples make any sense (easier CI separation), or should we use the examples/ folder.

I also agree that incorporating these simple setups into jaegertracing.io would be useful.

[yurishkuro]

Done in #1579