Open Telemetry Uncategorized, 12 Jan 2023

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: 2023-01-12 meeting

Description

Instrumentation: Messaging

A

Hey hello, it's.

B

C

A

I've last been here, you did not have a beard I. Think. Last time I had been in one of these meetings.

C

Yeah, uh that's been.

A

A while, then yeah.

C

I feel like I've had this for a little bit now, yeah.

A

Probably a few months.

D

C

A

It's important to stay warm as the weather gets colder.

C

Where are you based out of JV.

A

New Jersey and.

C

The U.S okay.

A

Where are you at.

C

In Portland Oregon, oh.

A

C

D

Just outside of.

A

Buffalo, oh nice, Northeast.

C

um Yeah I know that Aaron said that he wasn't gonna be able to make it today, but we could probably wait a few more minutes just to see if anybody else shows up. Otherwise this might be might be it for the day.

C

C

A

Planning on joining figured since none of us have been here: let's just bring a few just you know: Happy New, Year,.

A

As far as I know, he's planning on coming he's probably just be another minute.

C

Yeah no worries.

C

Well, cool, uh uh there's, David I'm, guessing a few more people are probably gonna trickle it, but we're um three minutes after so. We're probably jump in here uh welcome everyone. This is your first one of the our meeting of the year. um Welcome back! If you haven't already, please add your name to the attendees list and if you have anything you want to talk about, uh please add it to the agenda as well. We can jump in here one of the uh last things that needs to get done for the semantic conventions.

C

um So we can get this isn't even the right Milestone. um This Milestone of uh 112 out is this openpr to address this client um request. Http s, determination.

C

uh This is kind of a holdover from the refactor that was done for cemented conventions. Previously, all the TLs termination was just determined by this TLS field for request uh turns out. When you create a request as a client, it doesn't do anything with the TLs field. So um this attempts to try to do a little bit more by looking at the URL that it's sending it to to determine if it's a https, it doesn't actually annotate the attributes with https.

C

Given that the client isn't required to add a schema, but it does determine whether uh the https Port is included if it's not um 443, uh just because that's the standard Port. um So it's it's a minor detail, but it's still a bug that was looking to get fixed.

C

um Yeah but other than that I think that's the last thing for this release, so just kind of wanted to call it out. I, don't know if we want to time these releases, um this 112 and this v035 at the same time, b035 is coming along as well 76, which is um a step up. I think we can kind of dive into some of the open issues that are on this one as well, but ideally I'm, hoping we can get a release out, if not uh probably not this week.

C

Sorry Thursday, uh if not next week, the week after, um depending on how we want to couple uh these, these two releases.

C

um So that being said, I've got a few PRS or issues here that are still a part of the v035 for at least for metrics. um This one has been on the Block for a few weeks now this has to do with combining the pre-computed values with filtered attribute sets, um meaning the asynchronous counters and then when they interact with filters um uh uh after or it re-enters as well, this is hasn't changed too much.

C

There was a PR that was submitted here uh to my rebut emerged into this, but there's a few open issues here, so I haven't merged it yet, um but Aaron's also not on the call he's sick, so I think this might just get held up, um but actually let me that's good. Let me include this.

C

I'll include this here, I mean, ideally it should be included in this PR, um but I wanted to resolve a few issues before it got merged. um I. Imagine air is not going to be back until next week, so I think I'll wait till then if it takes longer than that, I'll probably just merge it and then uh address the issues myself. uh Although I do wonder about it, because there are reasons that I'm not seeing so I wanted to get some feedback on that.

C

But if you haven't taken a look at this PR, yet it's complex um and it's hard but I think it's important. So if you have some time David I know you had tried to take a look ahead. Have you been able to take another look at this.

E

I would like to see the example resolved before I I have I mean the code changes, look, fine, okay, yeah I, looked like it's clean and whatnot, and there are tests and stuff, but um I I still I I want to see the example running correctly and then I'll believe that it works and okay.

C

Yeah I think that's fair, um yeah. Okay, then I'll I'll plan on waiting for your review until I, get immersed in uh I'll expect that okay, um next up um there is this PR I, just opened I think it's yesterday, it's related to another redesign of the register, API called, which is already done, but this one I think is to be uh I, guess more more important um So. Currently our uh a synchronous instrument uh registration. So there are two ways to register an instrument. Currently we have a set.

C

You can register during its the instrument creation, but also you can register multiple after the facts. um The problem is that our current API actually has um a set of issues associated with it right now. um It's not compliant with the specification recommendations or the requirements in a few different places. uh They're listed in here, mostly like as a recommendation on the design, there's also a requirements, um uh man uh for how measurements are actually supposed to be recorded. So there's there's a few different things that we need to actually be able to do.

C

uh Most importantly, this distinguishing of instruments associated with each observation, I think, is really key. um It's also this recommendation uh from this API, which is uh probably confusing, because it's an API doc that this is listed for the SDK implementation, but that's a whole other thing.

C

um Another thing is also like to restrict uh which instrument actually gets updated.

C

We currently require the user to take the context that it was passed in the Callback and then pass it to each one of the instruments observed methods, and then we annotate that context with some sort of special flag or value uh to restrict that it's it's um it's a problematic solution in many ways, but the most important way is that it requires the user to properly propagate a context for valid uh operation, which I think is one of the main issues with that approach.

C

um It also you know, uh our current approach allows for the observation of unregistered instruments. A lot of observation of instruments from other meters in order allows for the observation of all kinds of different things. So um all of these things aren't really a great idea. uh This follows what we did in uh that single instrument, callback uh design and it provides this new interface. That's added here uh to the Callback called the multi-observer. The multi-observer accepts uh the instrument and it's a typed setup.

C

So this is kind of the nice thing is that it is uh checked by the compiler. It's uh statically tight, so uh you are sure that, like you're, not passing distance, um asynchronous interface here, you're actually passing something that you can. You know assure is given this value, uh but in this essentially like The Observer is passed to the Callback and the Callback is used to actually um or uses this Observer to actually update things so kind of an example of that.

C

From our Prometheus example, that's included in this PR is uh something that used to look like you would take the engaged call directly on the Observer method. Specifically passing this context. That's important! Now you just pass that gauge to this Observer and then you pass the value in the attributes that you want to observe, for that gauge is the the different design.

C

This is really similar to well, it's not only similar. It is exactly what the specification um one of its recommendations are, and it's similar to I. Think python does something very similar to this as well. For the multi, um it's a little harder uh because it's in Python they're dynamically typed, so this is, um it needs something similar to like just having this like float method, so yeah, I I think it's an improvement uh I.

C

It needs eyes, though, um and so yeah I just wanted to submit that make sure you get some feedback on that. This is definitely going to be a change for the API, so we needed to get this in it's something to deal with the compliance. So, ideally sooner rather than later,.

D

All right have we reviewed that approach with anyone from the TC or specsig to confirm that they agree with the view that that's the way to go.

C

um No, uh we haven't, but I mean it is uh I, don't know if I'd recognize the need for Authority there I mean it's a pretty um easy thing to do on our own, given that it's already listed in the API as recommendations, if that makes sense, like I mean I, I mean I, guess no directly but indirectly, given that this uh was already laid out as as the way to do it. I guess, if that makes sense happening.

D

Yeah yeah, I, guess um I, don't know, I'll have to go back and reread this portion of the spec, but my thing is: if we've already got it wrong once um should we have some outside eyes on what we intend to do now and to confirm that it's in fact right this time.

C

Yeah I mean I uh sure I think that's fair. uh I would also point out that I, don't think that other implementations are uh compliant with this either so yeah you may get um make it answers that require them to actually realize that this isn't what the specification requires. So I I don't know if a lot of people are familiar with it, but this is the example. I was talking about essentially like where python is doing some I actually don't know.

C

If this is the python implementation, I I looked a while ago, I think they do something similar, but they may also return a list um I think instead of this initial approach, but they provide some sort of result that result. Does that observe method which is I? Don't know uh that is exactly what we're doing here except the observed method is a types method um here, I think python. uh Based on this recommendation. They return a list because they can dynamically uh link some sort of instrument and measurement pair.

C

It's hard to return a list where this instrument essentially needs to be an interface and go because it's not statically typed, and then it requires an allocation for this uh slice, which is why uh in 3507, which is what the original proposal was, we switched to doing something more along this lives with the multi Observer. So then the allocations are not something that each callback has to do is is the difference there.

C

uh Okay, I think I had listed these two other items next on the agenda, uh uh which I think we can actually go through. Pretty quick I was going to move them, but uh this past week I was able to go through all these verification tickets. uh Most of them not most of them. Half of them were close. Half of them are requiring some sort of uh issue to be resolved. That is still open, uh meaning this redesign of the registration API.

C

So this includes any sort of asynchronous instrument like this one is not compliant because it doesn't actually conform to specification.

C

However, a lot of these also include like bugs that was found that were found in the specification, so they're kind of waiting on the specification to be updated before we can really say that we're actually compliant with it. uh So like this one, where we should be logging, a warning from our Co-op meter, which is not really what we want to be doing um so this is all the work for the metrics API, currently about like nine items in the block section. I think this is important to kind of take a look through.

C

If you haven't already- because this is the thing that's blocking the metrics GA, um both the API and the SDK as SK- would follow this, but other than that uh we already went through these well I. Guess we didn't go through this restructure. The registry register call method, but it's a very attic convenience transform that was introduced.

C

um Take a look at that if you want plus years in case anybody has something to talk about here.

C

uh Okay and then similarly.

C

I think there's a lot in progress here, there's seven, uh which I think we've kind of highlighted some of the bigger ones ah yeah I forgot I, wanted to add this um one of the things about this redesign of the registered callback API if we are going to be compliant with the specification I think after this is merged, there's actually no need to have an observed method on any one of our asynchronous instruments.

C

There's nothing in the API specification, the SDK specification or the data model specification that has any sort of statement, whether it's a recommendation requirement or an optional condition. That could say that you need to have an observed method. In fact, it's not mentioned at all. The only thing that's mentioned in the specification is that asynchronous instruments they record measurements through callbacks, so uh I think one of the important things to kind of call out is like here.

C

uh Yes, I, think it's here. um No it's here. We currently like this switches up to the Observer to be its own independent instrument, and the Observer method is literally just logging, an arrow saying that you should never actually call this um I. Think if we merge this, there's really no need to have an observed method. uh Given the API doesn't ever need a user to call in it only introduces the ability for a user to get an error, um so that seems like a really poor design.

C

I would try to uh motivate this I think after this PR has merged, but I I think that's probably the next step. If we were to do that, so I might say that there's like still another step for the metrics API. If we do move that just to clean it up and remove that, keep in mind that these are interfaces that we've listed as something that could add methods in the future.

C

So if the specification time came along and said like I, don't know why they would do this, but if they came along and said like asynchronous instruments can now be, you know measured synchronously and you need to be able to provide some sort of like inline observation method. We could add it in um but, like I said, it'd be really odd if we switch that into specification, so just food for thought, I guess more than an actual proposal. At this point.

C

um Other than that I think this is the only thing left in the metrics SDK beta that we had not addressed. I think this has to do with structure of how we want to maybe do some sort of pooling for metrics aggregation that needs somebody to take a look at there's still existing blocked issues.

C

uh This design dock for Doc structures is really just waiting on having this being a stable I think this should just get moved to like a uh maybe like a ga uh task instead of an up of data, because I think we'd want to do this after we have a release candidate, so I can do that after this, then the only other thing left is this.

C

Considering this uh math uh Nan proposal essentially like we have an allocation for our histogram data point type for the mid Max and not the summit of some, but um just because they're pointers. So there's a few different proposals here, there's a few different back and forth the conversation went both ways: I decided to propose this uh proof of Concepts, um essentially posing this. Where we have this new extrema type, this extrema type has it's very similar to what the SQL null string does where it says you know like.

C

uh If the value is zero, you can distinguish that zero value from being a set Zero versus a unset, uh zero value extrema by the set Boolean, meaning that this has been set or this hasn't been set. So what what this would do is, it would add, an extra Boolean to this data type uh for a pretty small overhead, but it would prevent the allocation I. Think that that's worth pursuing, there's a PR I'm, not exactly sure, on some of the feedback from Josh on that one, but I don't see him on the call either.

C

So don't really want to get too deep into the weeds here. um So I think that this is on actually has a solution to get it out of blocks. So I think it's just worthy of somebody coming in and saying like they want to support one method versus another, um which I think is looking good. So if you think about it like this needs, somebody to look at this is on the way to getting out and then there's a bunch of stuff in progress, but otherwise the beta is in line as well.

C

So we're getting close I guess is the way to say it.

F

Is the primary motivation for that performance like removing that allocation, or were there other things he was trying to accomplish I.

C

Think it was just performance.

C

uh Yeah I think it's just performance, because this will allocate once per collection cycle which isn't like the hot hot path. But it's not like a I. Don't know it's not a you know at startup kind of path, um but yeah I think that's the idea. I wasn't a big fan of this Nan uh proposal, because the zero value is not man, and so then you also have to have think about upstream and downstream. They have to understand this convention. That is not standard. Yep I.

F

C

Yeah, so that was what was said. Bogdan also had this proposal of having the allocation being something you know, there's a few different proposals in here so worth checking out. If you have um some thoughts on it, I I like this because it was just like already- has precedence in the SQL package and um it seems pretty straightforward. I, don't remember this being too big of a PR, actually uh yeah 60 lines or something like that. But it's yeah worth checking out, looks.

D

Like a lot of it's fixing tests, too, do we have benchmarks that show the the various options and how they perform.

B

C

I, don't no I, don't think so that could be useful. Yeah I think that whoever wants to pick this up I think that's a probably useful task. One of the things also is like benchmarks, are going to be good because they'll show allocations, but it won't show this overhead because you need to look at the um the structure size right, so you'll need to actually get into.

C

Oh man, it's been a long time since you can measure the structure size right, because it'll it'll nominally increase this, because it adds another Boolean um versus pointer to a float which is going to be I. Think these are all I guess it depends on the system. What the underlying pointer size is, but yeah.

A

So I mean there's going to be some overhead.

C

As well, that's not going to be in a benchmark but yeah that we should probably list it um qualitative uh or quantitative measures here.

D

Yeah I think is a general rule. Anytime performance is the primary motivation for a change. We should have a benchmark that shows that it's actually worth the change.

C

I agree: um I can try to yeah, actually I think I have time. I might be able to do that here. uh Yeah.

C

Okay, yeah I'll actually get back into this I. Put this up really quick, just as an idea but I think that's a good point. Anthony.

C

uh Okay, anything else.

C

D

I know you've created a number of issues in the spec repo um related to things you've found while doing this review, but are there any of those that we need to talk about here?.

C

I think uh that's a really good question.

C

um I don't have uh in the front of my mind an immediate answer, but let's just take a look really quick back at the metrics GA um I'm, going to try to time boxes a little bit.

F

C

But uh so this asynchronous instruments, this might actually have a few I hope. This is just the uh yeah naming, which should be done, anyways um that.

C

Oh instrument, General I, think has a few so.

C

Yeah, this is a oh God, so yeah this is one, so this restricted input value.

C

Currently, the API is required to restrict the input value of the counter values, which is like uh it's possible right, because we could build our own types that essentially only allow a specific value like it makes sense like you could do like a unit, but then how do you support floats as well so like? There are ways that the API could try to support this, but I really think this is the wrong approach and that this was not the intention of the API. This is something that's going to be restricted by the SDK.

C

uh It just needs to get clarified and it I think it needs to get signed off, because otherwise our API does need to get updated to support this Anthony. That would definitely be one of them.

D

Yeah I'm definitely with you on this SDK can enforce that if it wants but API, probably.

C

Not but it like made very little sense and I I have very little doubt that's what the intention of the original authors were, but I wanted to make sure that's understood, because otherwise we're wrong. This I think is done. I think it's just got merged, so this was a blocking one, because otherwise we would have to have changed our structure yeah. This is done um so then it's just the redesign, so that's all set that would have been one.

C

But um let's see oh yeah, here's the big one I think um another similar on that same line for the input value, but it's also the metric names. Currently, the specification requires the API or it seems to imply that instrument names need to be validated by the API again. This doesn't seem great if you're going to do like a no-op.

C

uh So then the no Ops going to give an error, but then, at the same time it's kind of red so like this is again something I think that, uh like we were just saying like should be done by the implementation, but not necessarily by the API um again just needs to get clarified the single instrument. Callback- this is done.

C

um This is done. This is done um and then yeah. This is the only other one that kind of like was front of Mind. Was this learning logging warning for the duplicate instrument, creation for the new OP meter? I? Don't think that we should do this uh put it in the blocks, because I don't think we should do this and I really think the Upstream used to get a no op implementation specified.

C

So we're not required to do this and clean up the API spec, because otherwise, like the API spec literally, has requirements that we should be doing this, um which is not ideal.

D

So it seems like most of these are stemming from that API over specification issue on canvasive.

C

Root cause I, think you're right, yes, so yeah we need that I think uh is is key, so yeah I think that that's that's that's a good way. To sum it up uh is exactly that.

C

um That being said, like I, don't think that there's anything that I opened or that I created a PR, for that is like changing the specification in a way that we then would need to change our API I think it was all just like these all look like errors of the spec. Can we fix these.

D

Right, it's, you know we'll need to change if the spec doesn't say no, no, we made a mistake. You really don't need to do that right.

C

Right yeah yeah, exactly like like this issue, should just be closed once the spec gets updated, I mean unless the spec comes back and says otherwise, uh but that's a whole other discussion yeah, um but yeah good good point, I think if there's there's three technical issues, but they really all stem from that same. uh The API spec over over um specifies uh that said. I think that my goal in this next week is to try to get a PR out to resolve that issue. um So stay tuned.

C

Cool um pause there just in case there's anything else. Otherwise we can jump into look talking about the launcher and then some godox stuff.

C

Awesome uh so uh Jamie Phil Tyler, uh you wanna jump in I'll hand it off to you. Yeah should.

D

We talk about the doc stuff first, because I imagine that might be quicker and then we can leave all the rest of the time for the launcher.

G

It might not be I.

A

Think that I think this will actually end up being pretty quick, um so yeah. So with the launcher, um you know we had had the design dock that we had talked about put up a while back um and then over time it's kind of stalled out, because you know different things: uh kubecon metrics, holidays, all kinds of things going on and in the meantime, we've sort of been using it still with um another distro.

A

Another wrapper um to you know see how it works, see how things go and, as we've gone, we've seen a few things. We want to change and um keep working on, and so we thought it made sense to instead of keeping it right now. It's um you know it's like a branch and a fork of the contrib repo and then there's the launcher. What we've done right now is we've pulled it into its own repo. At this point, um we feel like that's, going to make it easier for experimenting making changes. Things like that.

A

The goal is still long term. We want it to be in the contriba. We want it to be donated, contributed, you know, taken in all of that, but we know right now: it's not really a high priority, so just kind of wanted to give a update of where we are with that that we've moved it to a new repo. There I think uh Tyler just put it into the chat.

A

um It looks the same as our one branch was somewhere, but this way we figure it's kind of in a little bit more of a stable place for making changes to it and then, when the ghost Sig is ready to look at it again and consider moving forward or anything like that, um we can do that as like a dedicated project to move into instead of having it's kind of in a weird limbo, State and I know we've all kind of stalled off of it a little bit um so yeah I guess just wanted to see um if there's any questions or thoughts about that or if that makes sense, as far as an approach of what we're taking um and didn't want to just kind of do it without letting you all know, since obviously, we've talked about it.

A

G

uh Just one other quick thing that I'll add is to to the extent that you can get feedback about like sdks. um uh We do get some pretty positive feedback from some of our end users and then dog fooding about like hey yeah. You know that's kind of more or less sets things up.

G

The way that I expect it to um which is good, like it's sample size, is pretty small because again, like most people, they're like well I, just I'm gonna write the like amount of code that I need for my SDK and I'm gonna forget about it. So um yeah I, don't know if that's helpful at all, but uh it has not gone over poorly with people.

C

No yeah, that's I, think great feedback I also really like the approach of putting in its own repo for um experimental iterations. That kind of thing um I think that's the beauty of the go language.

D

Yeah and that's right in line with our current suggestion for contributions to the Contemporary pose, you know, go demonstrate usage and adoption, and this is a thing that we should include and then we can include it um so beyond totally cool with this approach.

B

I think an open question is we have some PRS out for the launcher? Would you rather us leave those open, or would you rather us close them for now.

C

That's a good question.

D

Are they going to be replaced by a later PR coming from this new repo, or do they do they serve a purpose now for people who are using something that currently exists and can trip.

A

Well, there's there's one PR that we are actively using like a branch, um but that we would with future updates here we're going to be using this dedicated repo. So we wouldn't want to like fully remove that Branch entirely until we're sure that it's not being used um but like as far as like the design dot goes or that Branch goes I guess the question would be.

A

How does it get reintroduced as a topic and or project to start on? Is it better to leave it open for feedback for anyone who might come by, including if anyone here says, okay, I, think we're ready now um or should it be closed and we have some other way of deciding hey? Let's revisit this in three months or something like that.

C

This is the pr for the design proposal, or is this something else I.

A

Think there's two so there's the design proposal is one of them uh and the other one is I. Guess I, don't know if it's a PR, yet we have a fork of the contribbo with a branch of the launcher.

A

um I don't recall. Actually, if it's in a PR to contribute yet or not.

C

Did we merge the uh Auto exporter? Pr is.

A

That no that's also still open. It's related. um We had been experimenting with it with the launcher. We hadn't specifically put it into this other repo. Yet because we figured this was still a more go contrib neutral. That is still something that I think might be interesting to explore. Some more.

A

um That is still an open, PR I think that's looking for for further feedback.

B

Yeah I would I just went looking and I think the only APR we have for the launcher is the design dock.

C

um Yeah I'd love to know what other people's opinions are on. I think that the design doc one is still a good idea to keep around. If we want to close it and reopen it, though I don't know, um the thing is like you have a new repo I think that's a great place to create issues associated with the design of the repo in the repo, um which would be essentially like feedback on the the design of the launcher there.

C

um So it seems like now there's kind of two places you would get feedback in the pr in contrib um and then you may also get issues in the repo and they would both be related to the design right.

A

And the repo is probably the better place, because that's where we're actively maintaining right and updating code and and making changes, so maybe it does make sense to not have that design, doc, PR or, if anything, have a note in there like direct any any questions or ideas or go check out this repo here um because yeah that is, that is ultimately the idea right is to see what makes sense for users what's helpful.

A

What's working what isn't working and if it's already in use, then that's the best way to see what's working or isn't working.

D

Right, yeah, I'm kind of involved as to whether the fpr stays open, but I would suggest updating it to put at the top and a comment at the bottom, a link to the new repo and say we're currently working on this over here.

D

So the people who show up who are likely to say at the top so that they write in the description so that, if they're looking the first page, I see it or at the bottom so that if they scroll all the way down, look at oh, what's the recent activity they'll see that too.

A

Okay, so um so we'll do that then we'll we'll put notes in the top and bottom that make sure to redirect anyone's attention to the new repo um and then again the idea, um the goal I guess again mentioning like, as Philip said about like we have had a lot of good feedback on it um as far as like streamlining the setup of Hotel, uh so we do think it's still really valuable to have in contrib at some point.

A

So I guess that follow-up question, then, is: how do we plan on revisiting that once, like I I suspect is probably like after some of this metrics push here um like? Is there something that we should plan on doing of of coming?

A

You know bringing it up as a topic again in say three months: is it something that stays stays on the the ghosting notes, or what do you think is the best approach there for um kind of having it around, because we don't want it to just be like here's our thing now over here we want it to be um part of control. Ultimately,.

C

So I would say um iterating on it in that repo and finding a successful proposal of something that is used by you know I'm guessing um honeycomb customers, but also like, hopefully, maybe some other. You know wild users um would be great, uh and so, if you have that and having feedback uh I, don't know where to capture that it'd be great, but once like you're saying I think once the metrics push is kind of um subsiding I know, there's going to be work afterwards, but like it's just subsiding, it's probably worth coming back.

C

I want to also keep in mind that our goal for the uh contribute repo is to partition up ownership, we're doing something similar in the Instagram um uh package. That's being added there. So I think like um having a design that is I, think uh verified by users to accommodate, need, I, think is good and then coming back and saying like look, I I want to propose to be an owner of this and um I. Think that's going to give a little bit more impetus to get it merged. I.

C

Think is the way to say that it's something that is I think cross-cutting. So it may be a little bit more involved than say something. That's like it's, your gender there's going to be a subset of contributors, but that's kind of my my take on that.

B

When it comes to contributing it back, uh we can definitely get feedback from uh known like users of the honeycomb distro, because we can have you know, conversations with them. Hope. That's not like I hope. It's not a requirement that non-honey comb users use it, because that would be a lot harder to track unless people that aren't honeycomb users are opening issues on the Repository.

C

um So I think it may be easier than you think, because GitHub actually is starting to track these sort of things, and then you can look into package docs to see what actually Imports it. um But to your original point, I, don't think it is a requirement. I think that that's like.

B

C

Think it's just it'd, be nice um I think you might be surprised uh how many other people are going to.

B

Be using how many people find it and end up using it. It'll.

C

Be cool, um and so I mean that definitely happens in a few packages are done uh organically.

A

So I think that's.

C

That's worth uh worth taking a look at just on your own, but yeah I think that's, that's probably fine, uh just just as long as there is some user verification, it also is I think appropriate, because it's open source code so like people outside of the or honeycomb org, are able to evaluate it. I. Don't think that that would um be an issue um really in.

F

C

C

um But yeah I mean I'm really excited about this. I. Do think that this is a great idea, because it helps should help uh speed up development. I think um uh the exam uh Hotel SQL is another great example of like somebody splitting off into a repo, and it's become extremely successful by the way. If you haven't seen that and you're listening to this recording, you should go. Take a look at the hotel sequel from XM, um it's a great repo um but yeah one of the things that I think is yeah.

C

I, think that's probably just the way I would leave it there again.

A

Okay cool so we'll you know, keep an eye on um and you know just keep up with metrics and how those things are going and all of that and we'll um put together some of that feedback and see where we're at in a couple of months and where we can what we can do to revisit it.

A

Thanks for all the feedback so far on it.

F

C

And uh I'll give you a Shameless plug. If you want that to speed up help uh review some of the metrics PRS.

F

C

No pressure, uh okay, um cool. We can jump on then Philip uh talk about the godocs on the website. Yeah.

G

Absolutely um so let me just start with just like a little update on docs and the website, just in general, uh independent go um so we're getting a pretty solid number of external contributions just across the board across all languages.

G

um A lot of them are like small drive-by contributions, which are great, like you notice something that's a little off or like hey this. Could this code sample could like look a little better or someone's like I, want to add, like a typescript sample to this this JavaScript thing?

G

um Those are pretty really really good, um and now that we have, we have two full-time maintainers couple times kind of a weird word, just just two actual maintainers, not like nominal maintainers, but like actual maintainers, who are also contributing content, um we're very active, especially on the docs side of things, and we have a couple of initiatives this year that we're that we're trying to go for um particularly like so last year.

G

We did a probably like 75 percent job of like just cover as many bases as we can of like what are all the things that you can just do period with like each major language like how do you create a span? How do you set an attribute? How do you get the current span or active span, whatever terminology you have, and and now like, that?

G

That motion is happening starting to happen with metrics as well, with JavaScript kind of leading the charge, but then.net is kind of following up closely, um but the next phase of that is like okay, there's, like a million things that you can do, but which is like the right thing for you to do.

G

Based off of your scenario or like the role that you're playing in your organization, like your your needs, if you are an operator versus if you are just like just a service engineer who and like you're, you happen to be writing go code but, like you know, you're, not like an open, Telemetry expert you're, just using it um you're you're, probably going to approach what you want to do very differently and like you're, like the things you're gonna have to care about, are also going to be different.

G

um We're gonna start to reshape Docs or maybe not reshape, just probably just add, but like add more of that kind of documentation, so that, like, if you're an advanced user, you can be like all right. Cool I have code samples and Snippets of text describing these code samples for every major thing that like matters for me, um but if I'm, not an advanced user, how do I even begin and how do I like get to the point where I can find what I need as quickly as possible?

G

um So that's like a whole year sort of Journey thing that we're trying to go on. um There's.

G

Also another thing around like best practices in general, but um we will probably call upon various maintainers for help with a lot of this, because, like from language to language, your best practices are going to be totally different and like, for example, in the.net world, do you have activity sources and you can create them and and give them a life cycle that is kind of different from like everything else, and it's like all right, what's like, where should this object live like what's actually the best way to create this thing and like how like, if should it be congruent to the life cycle of my application?

G

If not, why like, if I'm in this scenario, should I have like multiple Tracer providers? Why or why not, um and so I think you could probably expect various like pings along those lines, as we start to evolve the docks more and more of like all right cool. um This is the scenario. What are the recommended ways to actually use this thing?

G

um I, don't think, there's any action for you to take here right now. I, don't think we're at the state where we can really start doing this, but I would expect to like latter half of this year, we'll probably want to start having a lot more common conversations along those lines.

G

um But in the short term, um we've also been completing a movement to get all docs on into the website repo and like normalizing things across all the languages and Concepts and um eventually The Collector, to the extent that we can normalize things it's easier from language, SDK perspectives, but not so much other components.

G

um Go is the last one: that's not in the the website. Repo um and that's fine like it's not like. It wasn't like an active burning problem or anything.

G

um But one thing that we have found is that we get a lot more like drive-by improvements from viewers of the docs when it lives in that repo, because you can just click the edit this page button and it takes you like the GitHub editor and, like the vast majority of these, are like nice little quick fixes or like hey.

G

This was like subtly incorrect here's, a way that you can be more correct sort of thing, um and we found that, like the the languages that we moved into the repo, we get more of those kinds of contributions um from like a maintainer contribution. Standpoint like it's easy enough for us to. You, know, update in your repo. Do the sub module update like it's a little bit more toil but like we know how to do it.

G

um So the question that I so I would propose that we could probably we would prefer to have the go Docs in the website, repo under the go subfolder and and not have a sub module anymore. The question that I would close to you is: we believe that we will get more contributors to those docs that way, but they won't be be, like you know, adding metric stocks like level of contributions.

G

They will be like tweak this code sample or improve the wording of like how you're describing what a particular operation is, or something like that um and it'll, just kind of be like a semi-steady stream of that just forever.

G

um Is that like? How much does that matter to you? It's like! That's that's, like the one major benefit that I can see. That's like oh! This is like probably something that I think will happen as a consequence of this that will be different from the current state of the world. um Is that important to you.

C

uh I, don't remember us having a really strong opinion when this is originally proposed, to move it to our repo uh back in the day versus keeping it in the website box. I think it was a very slim choice to go with our repo, um so I don't see too much of an issue with that. The only thing that I do see is that we have a bunch of uh developers here that are looking for, like their first issue or a good something to work on um that documentation.

C

Work is always like really helpful uh and I guess we could just shuttle them over to that repo I. Don't know how like, if you know that might stifle it, but I, don't think it would staple it too much.

B

How how much documentation are we talking moving over develop like for? Are there other language sdks, there's like 100 of the documentation for that language, on the open Telemetry I o side, or is it like the launch launch like stuff like how to get started on open, Telemetry, iOS type, but the in-depth stuff is in the repo.

G

So the way that it works for the other languages is everything is on the site, except for API docs and, like an example repository if you have it so like, like literally like API reference stuff, we're not trying to host that at all, because a lot of those are like you know, each language has their own tooling for building that kind of stuff, and so we're not going to try to be in that business um but, like I've, been using the term conceptual docs, but like conceptual docs, is inclusive of like technical docs that include code, samples and stuff, but like how do I use a concept not like you know what are all the overloads for like this particular method, or something like that?

G

C

One of the things that did uh strike me is there's a PR a while ago. um Actually I might have a new fellow who opened it. I I, like I, don't remember, but it was like. We wanted to normalize the the getting started.

C

um Our current getting started, though also it like corresponded to an existing example that we have in the repo and it had some I, think really good like walk through, but as well as like practical, compilable examples um and I. Think that's one thing that I would like to persist. Not necessarily that example, but that, like um that, that ability to have like a well-established like go example, that is maybe referenceable, um because it's one thing, if you have the docs that are like writing about something, um but it's it's another.

C

If you actually have like somebody who's like well, what does that actually mean? They can go look at code, because a lot of the people that read that are you know, maybe code is the the language that can understand easier um and so I, just like the divorcing of where the code lives versus where the docs lives. That might also be something that would happen is that that would be lost in that process, because then we would have the FIB example like I'm, saying like it doesn't have to be.

C

The FIB example like it could be another example, but it needs to be like an actual code base that is referenced. I think is, is ideal, um is what I was trying to get at.

G

Yeah yeah, so so this is actually. This is a topic I wanted to bring to the comsig uh next time is so we've been placing a few of our hopes and dreams in the demo, app as like a canonical way to do. X in you know whatever language you're using in the context of a real world application, um but that repo is enormous and if you want to like build it and run it yourself, you now need to like compile grpc for rust and, like that's, that's the little Overkill.

G

If you're like well, I just want to figure out how to do this and go uh so. We have an unsolved problem here, I think of like what is an ideal, getting started sample on a per language basis that we can have. Where should that link to and how integrated should that be in the getting started?

G

Documentation, experience, um I, honestly, I, don't have an answer for that that that's like this is open problem to discuss that that I want to bring forward, and so um I will say like a yes acknowledge that concern and D like we have to solve that um One Way or Another like this year.

D

Yeah I just kind of want to Echo the importance of having both of those styles, of example, like the the community demo. App is amazing for showing here's what a system using open Telemetry looks like, but it's exactly that it's a large system and you can't really even make it smaller. It's also important to have for developers who are like okay, just how do I get started. What's the the minimal hello world, let me go see in context an SDK being set up and ran into the like there.

D

One of the things I had a group of interns do last year here at AWS was to create a a set of sample apps in all of the languages that we support in the ADOT distribution that have consistent Behavior. They all have the same the same set of endpoints. They do the same thing and reach out to S3 reach out, to um you, know an HTTP request um and generate a few metrics randomly, but with the same shape.

D

um So something like that where we could say: okay, you, if you have a simple app, it should do these things. It should emit traces. It should metrics if logs, are supported or submitted logs and have some sort of guidance about how they should look, and then it becomes kind of like a rosetta code across all of the languages of oh I. I see this in this language that I know how to set up. Now. Let me go look at the other one that I've got to work in and see the same thing being done.

D

G

We're we're kind of there we're we're like sort of there with the major languages in getting started today, whether there's no so like.

G

This is there's no like sample like set of samples or like uniform place where these samples are, but the getting started is pretty uniform in that sense, where it's like basic, how you set up SDK, how you like wire up, Auto and or instrumentation I guess I should say how you connect that with manual instrumentation tracing, how you add metrics to that um and how you get this to talk to a collector um and like each step is like, and this is what the output should look like, and if you run it, you make this changes.

G

This is now what the algebra should look like: um we've gotten like good pot, not a whole lot, but like positive-ish feedback about that, like nobody, nobody has complained and uh a few people have said. Oh, it was easy to get started, um but those are not backed by like- and this is the app that you can run that like verifies that the docs say it should look like this, and it does look like this.

G

um So, like I think we're we're part of the way there in terms of how we want this.

G

To sort of look and go would be a part of this, but um there's this unsolved piece of the code it's based off of where that exists, how it runs, and, um and also like policy decisions about it so like, for example, if we had that today for go I would I would make a policy that it would not include metrics just because it's not stable yet um and same thing for I mean well in the case of Ruby.

G

There is none, because there are no metrics but but like the bar, for that would be like stable API, so that you know we're not going to be signing ourselves up for much churn and um that that's not like really spelled out much on the website, but like this is kind of the policy that we have for doing anything with docs really um so.

C

Yeah I think that um I'd be down for whatever you you can get prescribed for an example. App um I have no idea if the example is HTTP, but I think that was one of the requirements, um but.

A

I don't know I just like I think.

C

That we could get especially new users, that's a great task for them to go like go. Do this like and I'm, not saying they have to get it right because, like there's, there could be feedback on the PRS, but it's just like starting on. That would be great having a demo app um that we could then have Universal across this so yeah. If there's any movement on that, an issue in a repo or just coming to the here, and we can create something um to try to address. That would be great.

G

Yeah, um so, okay, so let's say we decide. This is like this is the path we're going to follow for just scoping it to like getting started examples and like runnable applications and like this is where, like we think it's the best place where they all live, whether that's on you know, per language repository or you know, they're part of the the the SDK repositories or like there's just some single repo that has the samples, fruits language or something like that and we're like all right. This works with like other folks.

G

um Would that sort of be a point where you could say all right? We could. We could base the docs off of that, like I, I, guess I'm, trying to figure out like what a good order of operations here like if, if an outcome is that we could pull the godox into the repo like what good order of operations could there be to enable that or like if an outcome is like? Actually, we kind of want to keep it.

G

The same then like what are the the steps that we can take to try to make it easier for more contributors to improve the go docs and just like, if there's any process that we can establish to make any like uniformity, changes that we want to make to the docs. We can apply that to the godocs without there being um additional hiccups in that process. Like.

C

So I have no problem of moving the docs back to the the main website. That sounds fine, I would like beforehand. If you can create some sort of uh I, don't know build. Materials are designed for what an example needs to exist um in our repo before it was changed away from the FIB example. This is the only thing that I would I would recommend and like and having that having.

A

C

Is what I would want before we change the getting started essentially um for the godox is what I would prescribe. So you know, maybe if you know order operations, I would say something like um you know, synchronously having that example built at the same time moving the docs back to the main website and moving them out of the go repo I, don't think, there's a strong preference there and then once the example is done, then you know pring the docs to preference.

C

The new example instead of the the FIB example or or I, don't know or tell everyone to build the FIB example. I I, don't care too much about that. I just need to make sure there's overlap that there's an example that people can run for code. Okay,.

G

Okay, I think this is.

D

G

um Okay, so so what I'll propose with the the commsig then, um because this is going to be our uh one of our discussions next week, I think um is uh we need to figure out this example's issue.

G

um We're gonna have to figure it out. Anyways so might as well make this the impetus um and, if we're comfortable with something we'll take that to you all and say like hey this, this is how we want to handle like, in particular the getting started. Example I think that's, that's the most important one. The rest are like you know how do I, how do I get the current span, as you don't necessarily need a dedicated example for that, like a small snippet.

C

Works but no you don't um you know. Ideally we could reference code, but.

F

G

C

A great starting point is what you just said: okay,.

G

Yeah I would I would probably feel most comfortable with us figuring that out and then sort of vetting vetting this with you all before we initiate it and kind of move.

G

um Just because this this is of particular importance. I think yeah that.

C

Sounds good, um let's plan on uh resyncing next weekend, I do or sorry next week um we are at time so uh I know people have to drop in a respectful time, so we'll plan on that if Carter uh Philip, if you want to reach out to me at slack for any other issues, we can touch there. Otherwise, we'll see everybody in a.

D

Week question is: is the commsake meeting on Monday because it's a holiday where's, the next meeting on the 30th.

G

um Yeah, we're probably gonna have to move it, because that is a holiday yeah. um Okay,.

C

Yeah in two weeks time well.

G

But yeah we'll we'll figure, it I mean we. We do a lot of stuff, async anyways, so um we'll probably have something by next week. This time.

C

Okay, uh well we'll plan on see you then at least in two weeks, if not sooner, all right, cool thanks everyone for joining uh see y'all next time.