Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add upgrade directions in FAQ #809

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add upgrade directions in FAQ #809

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions content/docs/next-release-v2/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ One benefit of Cassandra backend is simplified maintenance due to its native sup

[issue-166]: https://github.com/jaegertracing/jaeger/issues/166

## How should I upgrade to a new version?

Jaeger is stateless for the services themselves, the state all lives in the data store. We try to avoid any kinds of breaking changes in our upgrades, so typically the order does not matter. However, upgrades should be done with the following order of operations. If you are running Jaeger in a fully distributed environment you should upgrade the Jaeger query role first, followed by the collector role. You should note that upgrading both sides of the Kafka data flow should be done as close to simultaneous as possible to avoid issues with data being written and read by different binaries.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear to me what exactly is the objective of this. The question is very open ended. I could see giving a bit most structured answer to that.

Should this really be in FAQ? I'd thin Deployment page would be a natural home for a section "Upgrading Jaeger"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The objective is to give guidance on the order to upgrade components per #117 What other guidance do you think we should provide?

I don't think deployment has much on lifecycle aside from cradle, but we can add it there instead of here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Upgrading versions is part of the deployment story, so I would naturally look there for information, not in the FAQ.

As far as text:

Jaeger microservices (components) are stateless, all the state lives in the data store(s). When no breaking changes are introduced in a release the order of upgrades for individual Jaeger components does not matter.

We try to avoid any kinds of breaking changes in new versions, but sometimes they are unavoidable and will be clearly called out in the release notes. In those cases the safest upgrade order is by starting from the end of the ingestion pipeline: first jaeger-query, then jaeger-ingester if using Kafka, then jaeger-collector. This order ensures that the receiving component is running on a newer version and is capable of understanding any protocol changes from the other components earlier in the pipeline before those are upgraded.

Finally, sometimes we introduce storage schema changes that may require some pro-active steps before upgrading Jaeger components. Such changes will always be marked as breaking changes in the release notes and contain specific instructions for upgrading.


## Why do Jaeger trace IDs look differently in Kafka and in the UI?

Under the hood, at the data model level, the Jaeger trace IDs are a sequence of 16 bytes. However, these 16 bytes can be represented in many different ways:
Expand Down
Loading