Jaeger client for PHP

[yurishkuro]

OpenTracing API for PHP is available: https://github.com/opentracing/opentracing-php

[jcchavezs]

Finally we have https://github.com/opentracing/opentracing-php, shall we update the issue @yurishkuro ?

[black-adder]

Just FYI, we do have someone currently building out the php client: https://github.com/jukylin/jaeger-php

[otisg]

@jcchavezs are you referring to https://github.com/jcchavezs/jaeger-client-php ? From what I can tell, https://github.com/jukylin/jaeger-php is further along. Maybe joining forces with @jukylin would be better?

[jukylin]

It's good idea .jukylin/jaeger-php depend on opentracing/opentracing-php, and we can make it more better together.

[jcchavezs]

I believe this one is looking great: https://github.com/jonahgeorge/jaeger-client-php I am thinking on joining @jonahgeorge.

[taoso]

The opentracing/opentracing-php is far from stable. Even it has a 1.0.0-beta release, its latest master branch breaks the API.

So I suppose to only depend on it when it hits a 1.0.0 release.

[felixfbecker]

The opentracing/opentracing-php is far from stable.

And so is jaeger-php. There is no reason to not start developing the Jaeger implementation. It's easy to change the API.

[taoso]

@felixfbecker It's easy to change the API until you use them in production environment.

[felixfbecker]

If you use a version clearly documented as unstable in production that's your own risk and no reason to artificially slow down development progress.

[yurishkuro]

In #366 (comment) @lvht said:

would you like to accept the lvht/jaeger-php as the official PHP client of Jaeger?

I would like to hear from other interested parties. I myself don't have a strong opinion since we do not write applications in PHP at Uber.

[tylerchr]

We have quite a bit of duplicated work going on here (or parallel efforts, depending on your perspective):

• @yuklin is working on https://github.com/jukylin/jaeger-php
• @jcchavezs is working on https://github.com/jcchavezs/jaeger-client-php (forked from jonahgeorge)
• @jonahgeorge is working on https://github.com/jonahgeorge/jaeger-client-php
• I'm working on https://github.com/qualtrics/jaeger-client-php
• @lvht is working on https://github.com/lvht/jaeger-php (apparently forked from juklin)
• @allflame is working on https://github.com/code-tool/jaeger-client-php
• @korchasa is working on https://github.com/korchasa/jaeger-client-php (forked from allflame)

Each of these are in various states of feature completeness, stability, opentracing-php compatibility, PHP5/7 compatibility, production-readiness, and maintenance.

Rather than balance many separate projects with one owner each, I propose we make an effort to merge these all into one repo with many owners. This will produce a much higher-quality client than if we each go it alone. @jonahgeorge and I have previously discussed merging our efforts, so maybe that's a place to start. Barring any objections, I'd be happy to own facilitating that.

[jukylin]

It's interesting

[yurishkuro]

100% in favor of merging the efforts into an official repository under https://github.com/jaegertracing.

Might be useful to have a feature comparison among the existing implementations, pros/cons. The parent ticket #366 lists the common requirements for an official client lib.

[allflame]

@tylerchr first of all, I'm personally in favor of combining efforts into a single library.
However, when I was looking over for existing implementations I failed to find one that was well-enough built and used a stack-based approach to automatically define parent-child span relationship.

I'm not sure we can advise to use our library at this point since it lacks documentation and tests, but we are proud of API stability that we were able to achieve.

[felixfbecker]

Could you explain what you mean by stack-based approach? How would that work with concurrent programming or an event loop?

[yurishkuro]

I assume "stack-based" refers to some form of active span management, which is important but should be solved at the OT API level, just like it was in Java/Python. I think that concern is very different from actually having an official PHP client for Jaeger, even if it doesn't have active span management features yet (because official PHP OT API doesn't have them).

[allflame]

@felixfbecker you start a span - an active context is put on stack, you finish span - you pop the context from the stack. This was (our own) solution coming from requirement not to pass context from layer to layer in the application itself. This is discussed and "rationalized" in some go applications, but it's really different language where this is a general approach.
About concurrency and event-loops: of course, your tracer should be thread-safe in order to work properly there. This is also mentioned in Opentracing documentation. Since you can still inject context and basically clone your tracer in another thread, I don't think this is a concern until async/await support.
As for event loop - I specifically added a possibility to manually specify parent context.

@yurishkuro You are completely right. This was never thought to be an "official" implementation. It does follow the formal requirements and have all necessary (at least for my use-case) features

[tylerchr]

The stack abstraction doesn't work for concurrent or event-loop-based languages, but PHP isn't concurrent or event-based. As such, a stack does model the in-process lifecycle of a trace very neatly for PHP, in what I believe is a closed-form way. A "push" starts a new span (which is a child of the span on the top of the stack if one exists), and a "pop" finishes the top span on the stack. It also has the nice advantage of providing a way to identify all the unfinished spans and close them, in unusual cases like when the script ends without completing execution (usually because someone called die() or exit(); in such cases it's nice to not lose your whole trace because the root span never got finished).

We did the same thing at Qualtrics (see this gist for our basic approach), but our stack implementation is outside our jaeger-client-php implementation and just works on the opentracing-php API. This seemed ideal because it offered a nice separation of concerns, without forcing my stack implementation on all users of my jaeger-client-php package. To @yurishkuro's point, should some kind of "active span management" functionality be standardized for PHP, it'll be relatively easy for us to replace.

[jukylin]

I release to v2.0.0-beta https://github.com/jukylin/jaeger-php

[sgnrslv]

Hi there.

We've implemented Jaeger client as PHP extension.

Probably, there is a lack of compatibility with all OpenTracing API concepts, but the extension covers all our needs and proved itself in a production battle ;)

So feel free to give it a try.

[sagikazarmark]

An extension sounds like a great idea, however I'm afraid that in many cases it's simply not an option. It would be awesome though if there would be a userland implementation which could be installed as a fallback when the extension is not available.

Anyway: I haven't worked on a Jaeger PHP client (yet), but I'm willing to join the coordination effort if it brings us any closer to the solution. (Maybe it even helps that I'm not biased 😉 )

I briefly looked into the libraries listed by @tylerchr , they all seem to follow similar concepts. There are differences in quality and implementation of course.

I agree with @yurishkuro that the first step could be a feature comparison. I would also take a look at the concrete solutions as well.

I know some of you expressed support for one or another libraries, but personally I think the best thing to do at this point is to agree on some key concepts based on the above comparisons, and start building a new library under the official jaegertracing org, even if that means copying over a bunch of source code.

That way everyone can equally contribute to the effort, the current libraries stay intact and even when copying source code, we can review the pieces again one by one.

[isaachier]

I'd highly recommend the extension route if possible. We already have a C++ client and I've been working on a pure C client as well.

[isaachier]

@sagikazarmark what you do mean "would not be an option." A huge amount of PHP is implemented in terms of C extensions.

[sagikazarmark]

In many environments custom built PHP extensions are not allowed or not possible for whatever reasons.

[isaachier]

We could package it via pear or wtvr

[sagikazarmark]

I guess it's not a coincidence that many extensions have a userland implementation as well (protobuf, twig to name a few). I'm not arguing that an extension would be better for a number of reasons. But it doesn't suit everyone.

[jukylin]

No problem

[yurishkuro]

Sounds good. I booked a few issues in the repo that need to be resolved before the move: https://github.com/jukylin/jaeger-php/issues/created_by/yurishkuro

[JonasVerhofste]

I don't think the other projects, see this previous comment, should be disregarded. Some of them have features the other one does not have, for example the transport options of the qualtrics-one. I don't know if the matrix mentioned earlier is up to date, can't see an edit-date, but it's probably a good idea to update it, both the requirements as well as the compliance of those requirements.

Also, not sure if there's been a decent effort in trying to merge (some of) the projects together and if the concerning devs are (still) up for it. Would be a shame to lose functionality provided by a project because of the adoption of another one, in my opinion.

cc @jukylin @jonahgeorge @qualtrics (@tylerchr) @code-tool (@allflame) (not sure if organisation-mentions work)

[zzarbi]

@JonasVerhofste From my perspective it doesn't really matter which project we start on as long as we start on a project. Once we have a starting point we can start merging features. My goal is to get an official package that I can use on production with a community behind it.

[JonasVerhofste]

@zzarbi I get where you're coming from, but it'd be pretty stupid to blindly merge one project and we'd afterwards have to port all the functions from another one, when the other way around would've been less work.

I'm not saying that's the case here, haven't had the time to take a thorough look at the projects yet, I just want to make sure the choice is thought through and we're not creating unnecessary work for anyone.

[zzarbi]

@JonasVerhofste 100% agree and I wish someone did that in 2017 before everybody started expending their own implementation. I've looked trough the implementation of https://github.com/jukylin/jaeger-php for a POC and I can tell you there is a lot to do and a lot to clean up. This decision can easily be undone once we have an official repo with some people backing it up.

[allflame]

As for usage:
Company name: Evoplay
Project name: hundreds of them
Usage: prod
Number of Services: 120+
Volume: Hard to estimate, sampling with 0.001, cleaning 2TB Elastic index every 2 days
I would say the packagist statistics can be taken into consideration as well

As for the libraries:
I've got a lot of questions why would we write our own when there was already 2 or 3 in place, and I think I answered them here as well:

• OOD - existing libraries (at least at the time being) suffered from multiple anti-patterns (static calls, interface segregation, encapsulation violations etc)
• There was no way to inject tracer without putting random tracer-related stuff within the application classes, methods etc like Lock::acquire() -> Lock::acquire($context) etc
• There were no integration with popular PHP frameworks

I wouldn't go so far as to suggest that our version is better and would advocate on that behalf.
But it's

• better for us and for some other people who apparently (according to packagist) are using it.
• not designed as a high-level language translator from Go/Java/Javascript version to PHP which is good and bad at the same time
• can be integrated into any application without messing with application-level interfaces

[JonasVerhofste]

I wish someone did that in 2017 before everybody started expending their own implementation

@zzarbi Well, no turning back time. We'll just have to do with what we have right now.

This decision can easily be undone once we have an official repo with some people backing it up.

What do you mean? I don't think undoing the adoption of one project to adopt another one is something that can easily be done, if that's what you mean.

I would say the packagist statistics can be taken into consideration as well

@allflame That's something to go on indeed, but the statistics are quite mixed imo. @jukylin's is starred most, but yours is downloaded more. That's exactly why I said to not to disregard the other ones and make a comparison matrix. Map all the features and see which one has the most support, as to make the transition from the different community libraries to the official library as seamless as possible.

@yurishkuro any opinions on the matter?

[zzarbi]

@JonasVerhofste For instance what @allflame is talking about, like lack of OOD in @jukylin's implementation is something that can be fixed. A lot of what we're talking about is based on preferences which is why I proposed to stick to the first implementation and then to address all the concern that can be addressed.

The only thing that I think would be hard to change is the choice between a PHP extension or pure PHP. Beside that there is always going to be something we can do better regardless of the decision we make first.

[yurishkuro]

@JonasVerhofste this issue has been in analysis paralysis for almost two years. I tend to agree with @zzarbi that at this point it's more important to make the choice rather than make the best choice. Unfortunately, I have zero domain knowledge of PHP, and looks like the other core maintainers are in the same boat, so we cannot provide much architectural guidance. Organizationally, the key to success of a client library is having several knowledgeable and active maintainers, as well as active user base.

[tylerchr]

Agreed, it's past time for us to pick something and commit to it. Despite authoring one client, I'd much rather have a standard version than see it be my own (which is far from the best one, anyway!). My sense is that each author has an implementation that serves their current needs, and has a lack of either time or interest in building it out further. But this isn't @yurishkuro's problem to solve.

Organizationally, the key to success of a client library is having several knowledgeable and active maintainers, as well as active user base.

For this reason I would really like to see @jukylin, @allflame, @jonahgeorge, and myself all stay involved behind one client. Would each of you be willing to spend time porting your implementations' unique features over to a chosen codebase and trying to use it in your environments? If so let's pick the one with the cleanest design and do that.

A couple things I like from each of the others:

• jukylin/jaeger-php looks like the most feature-rich and actively developed.
• code-tool/jaeger-client-php seems to be the most idiomatic PHP and has the cleanest repository layout, to my eye. It also has the most Packagist downloads for what that's worth.
• jonahgeorge/jaeger-client-php is built against the most recent OpenTracing API (1.0.0-beta5) and is the only one of these with a CI pipeline.

Given just this 20-minute exercise, I think I'd be most inclined to take the @allflame's and start bringing things over from the others. Thoughts?

Flushing out the comparison sheet may or may not be helpful in assessing the relative merits. In any case I've opened it up for public edits if that's an exercise someone wants to undertake.

[tylerchr]

@yurishkuro Would OpenTelemetry affect this thinking at all? One potential solution is just to leave all our jaeger-client-php clients behind and join up on an OpenTelemetry client instead. It may still be too early for that though.

[yurishkuro]

@yurishkuro Would OpenTelemetry affect this thinking at all?

Yes, that is another option. In the longer term we're open to abandoning native Jaeger clients in all languages and fully switching to support OpenTelemetry default implementations (provided that we can get feature parity with Jaeger clients). I don't think this would happen for at least a year for the most used Jaeger clients (essentially the current official ones), but since we don't have an official one for PHP we can go directly to OpenTelemetry.

[zzarbi]

If we're planning to move to OpenTelemetry later, I think it would still makes sense to pick any of the current implementation. I picked @jukylin's only because it was the first one and so many other implementation forked it as well. I did not picked it based on implementation, features, coding style because I believe it can be address with some help.

[zzarbi]

FYI as pointed out earlier in this thread by @allflame, his repo has no documentation. I've been going thought his bridge implementation for Symfony and I don't think we would be able to help adding the documentation at first. Regarding @jonahgeorge his implementation requires php 7.3 or PECL/hrtime.

[jonahgeorge]

As an aside, I’m all for supporting the OpenTelemetry client

[MartijnZuijd]

is the effort to come to a single solution/combined effort still ongoing?

[andypost]

Expect it more tricky now in a light of coming PHP 8.0

[zzarbi]

I think you would have better luck overthere https://github.com/open-telemetry/opentelemetry-php

[jpkrohling]

I for one encourage you all to collaborate on OpenTelemetry's client!

[jpkrohling]

I'm closing this, as I don't think we'll progress with a client for PHP. If you disagree, leave a comment and I'll reopen.

[altexdim]

Hey everyone
What's the best library to use with Jaeger for PHP?
I didn't quite understand if we should use opentracing or opentelemetry api for the most recent jaeger backend, because it looks like even all-in-one build is based in opentracing, and opentelemetry is deprecated.

[saktib]

dn't quite understand if we should use opentracing or opentelemetry api for the most recent jaeger ba

Hi @altexdim , I would recommend using the official opentelemetry library https://github.com/open-telemetry/opentelemetry-php as there are few reason behind it.

• As you can see on https://opentracing.io/ , now Opentracing and OpenCensus have merged to form Opentelemetry so you can use one single library to have your traces and metrics collected.

• Currently seeing the active development status between opentracing and opentelemetry, it can be clearly seen that opentelemetry is having recent commits whereas opentracing had the last commit on January.

• Last but not least, opentracing currently supports HTTP sender only, and the reason why there are few forked opentracing repos out there as you can see above have the UDP support and are duplicate, and in the current scenario though opentelemetry support http sender, there is PR open to have the UDP support in.

[altexdim]

@saktib Thank you very much for the quick reply

Actually I completely agree with you, and I was going to try open telemetry with jaeger recently. The idea was to set up the all-in-one jaeger docker container, and install open-telemetry php library, and make it work with very basic setup, just for the proof of concept. But when I opened up the latest documentation regarding jaeger they say that the latest all-in-one docker container with jaeger supports OpenTracing API, and nothing is stated about open-telemetry. They have links to the client libraries for OpenTracing client libraries, and again no links to the open telemetry libraries.

The problem is that It's not clear from the jaeger documentation how to install and how to use open telemetry client libraries with its all-in-one docker container (and it's not even clear if it's possible at all). Do you have by any chance links to any articles that can help me with installing and setting up jaeger (preferably all-in-one solution) + open-telemetry (for php)? Some examples would be very useful.

The other issue is that https://github.com/open-telemetry/opentelemetry-php doesnt support UDP yet (which doesnt look good for production environment). I'm looking forward to seeing your PR merged as soon as possible (https://github.com/open-telemetry/opentelemetry-php/pull/246/files). Is there anything I can help you with to make it merged faster?

[jpkrohling]

they say that the latest all-in-one docker container with jaeger supports OpenTracing API, and nothing is stated about open-telemetry

Where did you see this? We might need to change our docs, as the backend has nothing to do with OpenTracing API.

They have links to the client libraries for OpenTracing client libraries, and again no links to the open telemetry libraries.

This page might also need some rewording, as it might be causing some confusion. Jaeger client libraries are implementing the OpenTracing APIs, but there are certainly other clients that folks might use to send data to a Jaeger Collector.

The other issue is that https://github.com/open-telemetry/opentelemetry-php doesnt support UDP yet (which doesnt look good for production environment).

An alternative might be to have an OpenTelemetry Collector as a sidecar to your deployment, playing the role of a Jaeger Agent. You can then make a gRPC connection between your application and the local collector, so that data is offloaded quickly from your application. You should also configure the gRPC client to not retry/queue failures, likely making it as lightweight as Jaeger client sending data via UDP to a local agent.

[altexdim]

Where did you see this?

I have a couple of links for you

the documentation with OTEL support 1.21 - https://www.jaegertracing.io/docs/1.21/opentelemetry/

At the moment Jaeger OpenTelemetry binaries are experimental and the configuration or behavior can change. The current progress can be tracked via issues tagged as area/otel.

the latest documentation doesnt even have OTEL section https://www.jaegertracing.io/docs/1.22/deployment/

and even there there's nothing about otel but only about opentracing https://www.jaegertracing.io/docs/1.22/features/
Native support for OpenTracing
and nothing about OTEL support

https://www.jaegertracing.io/docs/1.22/getting-started/ - this is all-in-one docker container + getting started documentation - again there are references to opentracing and no OTEL
Check the Client Libraries section for information about how to use the OpenTracing API and how to initialize and configure Jaeger tracers.

I also didn't quite understand about removing OTEL collector from the jaeger backend - #2828
Remove existing OpenTelemetry Collector code

I'm very confused about official support of OTEL in Jaeger :) I coudnt find anything in the official documentation, sorry. It would be nice to have some examples, and all-in-one docker container with the demo client which interacts with all-in-one backend using OTEL, but also without documentation it's not easy to even understand that there's an alternative to opentracing in Jaeger

[saktib]

@altexdim ,
I tried using jaegertracing all-in-one which runs all Jaeger backend components and UI as well so that we don't have to run any sidecar, this is my jaeger container setup on my docker-compose.yml

 jaeger:
   image: jaegertracing/all-in-one:1.20
   environment:
     COLLECTOR_ZIPKIN_HTTP_PORT: 9412
   command: '--log-level debug'
   ports:
     - "5775:5775/udp"
     - "6831:6831/udp"
     - "6832:6832/udp"
     - "5778:5778"
     - "16686:16686"
     - "14268:14268"
     - "14250:14250"
     - "9411:9411"
     - "9412:9412"

To use the opentelemetry client library, you can go through the examples https://github.com/open-telemetry/opentelemetry-php/tree/main/examples , specifically the AlwaysOnJaegerExample.php which shows the way how the exporter object is getting initialized using jager.

[jpkrohling]

I see the confusion. The mentions to OpenTelemetry are related to the backend component, collector. We removed the documentation for it because the previous work on making Jaeger based on OpenTelemetry Collector has changed.

The mentions to OpenTracing are about the client APIs. The Jaeger Client libraries implement the OpenTracing interfaces so that applications instrumented using the OpenTracing APIs could use the Jaeger Client with it.

In the context of this ticket, PHP support is something that is relevant for the client libraries only. That said, no official Jaeger Client will be released for PHP, but you are certainly encouraged to use the OpenTelemetry PHP API and SDK, which should provide an exporter for Jaeger Collector.

I hope this clarifies a bit.

[codekissyoung]

ok , I Know that ！ PHP is the language that raised by stepmother . Do not have an Official Client for Yaeger Really Bothered me T_T