Correlation-ID feature allows 'tagging' a call to a Backend command with a String ID, and this ID will be appended to all log messages that result from this command. http://www.ovirt.org/wiki/Features/TaskManagerDetailed In REST-API, we would like to enable the user to pass a correlation-ID when he activates actions. I have two questions: 1) what's the name you'd give this parameter? job-id? batch-id? flow-id? command-id? correlation-id??? 2) I've already implemented this as a url parameter. Are there objections? The only viable alternative I see is as an http header, which doesn't feel right. It's not an option to pass it in the XML body, because sometimes there is no body, for example, in DELETE commands.

> Correlation-ID feature allows 'tagging' a call to a Backend command > with a String ID, and this ID will be appended to all log messages > that result from this command. > > http://www.ovirt.org/wiki/Features/TaskManagerDetailed > > In REST-API, we would like to enable the user to pass a > correlation-ID > when he activates actions. > > I have two questions: > > 1) what's the name you'd give this parameter? job-id? batch-id? > flow-id? command-id? correlation-id??? > > 2) I've already implemented this as a url parameter. Are there > objections? > The only viable alternative I see is as an http header, which doesn't > feel > right. It's not an option to pass it in the XML body, because > sometimes > there is no body, for example, in DELETE commands. Hi Ori, Is the intent here to allow correlation between multiple backend actions initiated from a single restapi call, or an over-arching correlation across multiple restapi calls? If the former, then I'd agree with Yaniv, just generate the ID internally and return it as a response header. If the latter, then allowing it to be optionally set via a request header, seems more natural to me than a URL parameter because this is additional out-of-band data that aids in log interpretation, as opposed to something directly germane to the interaction with the target resource.

>> Hi Ori, >> >> Is the intent here to allow correlation between multiple backend actions >> initiated from a single restapi call, or an over-arching correlation >> across multiple restapi calls? >> >> If the former, then I'd agree with Yaniv, just generate the ID internally >> and return it as a response header. >> >> If the latter, then allowing it to be optionally set via a request header, >> seems more natural to me than a URL parameter because this is additional >> out-of-band data that aids in log interpretation, as opposed to something >> directly germane to the interaction with the target resource. > > both. > engine auto-generates this if not provided and domain is single command. > but client can pass this to see all events or multiple commands running > in parallel as part of same single client logical action. Right, when user passes a correlation ID on the http request, all calls to the Backend, that are done in the context of this request, will have this correlation-ID (and thus appear in the log as part of the same operation). But when I think about it, why should the user be involved? If a REST action - for example restore-snapshot - involves more than one call to the Backend, REST-API (not the user) can decide to always attach a hard-coded, descriptive correlation ID to these calls.

In trying to justify letting the user set the correlation ID, I came up with the following scenarios: * the user wants to analyze an action in the log, but the server is shared by many users. It would be easier to look for "ori's_restore_snapshot" than for the generic "restore_snapshot", because maybe other users restored snapshots. * tester wants to run the same action 50 times with different parameters, and see the actions in the log as: "restore_snapshot_test_1", "restore_snapshot_test_2", etc. So in summary, I think there is some value in letting the user set the value.

Ori

Still need to decide about this: > 1) what's the name you'd give this parameter? job-id? batch-id? > flow-id? command-id? correlation-id???

> On 05/06/2012 10:03 AM, Ori Liel wrote: > > Still need to decide about this: > > > >> 1) what's the name you'd give this parameter? job-id? batch-id? > >> flow-id? command-id? correlation-id??? > > job-id will confuse us with engine's job-id which is a single command > today. > correleation-id is pretty long and confusing as implies on > correlation > of something. > > I'm for flow-id or batch-id. > batch-id sounds the right one to me, as this is identifying a batch > of > calls.

How about log-id? It isn't supposed to be unique, or of any format, it's just used to log calls, so log-id is the most natural (or log-tag or whatever name you prefer). Also I think it's more of a header-type parameter since it's metadata for the call, not an actual parameter that influences the outcome of the "flow".

_______________________________________________ Engine-devel mailing list Engine-devel(a)ovirt.org http://lists.ovirt.org/mailman/listinfo/engine-devel

From: "Ayal Baron" <abaron(a)redhat.com&gt; To: "Ori Liel" <oliel(a)redhat.com&gt; Cc: engine-devel(a)ovirt.org Sent: Sunday, May 6, 2012 11:45:22 PM Subject: Re: [Engine-devel] REST-API: Exposing correlation-ID ----- Original Message ----- > >> On 05/06/2012 10:03 AM, Ori Liel wrote: > >> > Still need to decide about this: > >> > > >> >> 1) what's the name you'd give this parameter? job-id? > >> >> batch-id? > >> >> flow-id? command-id? correlation-id??? > >> > >> job-id will confuse us with engine's job-id which is a single > >> command > >> today. > >> correleation-id is pretty long and confusing as implies on > >> correlation > >> of something. > >> > >> I'm for flow-id or batch-id. > >> batch-id sounds the right one to me, as this is identifying a > >> batch > >> of > >> calls. > > >How about log-id? > >It isn't supposed to be unique, or of any format, it's just used > >to > >log calls, so log-id is the most natural (or log-tag or whatever > >name you prefer). > > > >Also I think it's more of a header-type parameter since it's > >metadata for the call, not an actual parameter that influences the > >outcome of the "flow". > > I actually believe you're right, it probably is better to pass this > parameter as > an http header. You've changed my mind about this (objections, > anyone, to passing > it as a header as opposed to passing it as a url parameter)? > > About log_id - it could sound like there are numerous logs, and the > user is asked > to specify the ID of the log he wishes to write to. But perhaps: > log_entry_id? op_id? (operation_id)

> > Thanks, > > Ori > > > > _______________________________________________ > > Engine-devel mailing list > > Engine-devel(a)ovirt.org > > http://lists.ovirt.org/mailman/listinfo/engine-devel > > > _______________________________________________ > Engine-devel mailing list > Engine-devel(a)ovirt.org > http://lists.ovirt.org/mailman/listinfo/engine-devel > _______________________________________________ Engine-devel mailing list Engine-devel(a)ovirt.org http://lists.ovirt.org/mailman/listinfo/engine-devel

>>>>> 1) what's the name you'd give this parameter? job-id? batch-id? >>>>> flow-id? command-id? correlation-id??? >>> >>> job-id will confuse us with engine's job-id which is a single >>> command >>> today. >>> correleation-id is pretty long and confusing as implies on >>> correlation >>> of something. >>> >>> I'm for flow-id or batch-id. >>> batch-id sounds the right one to me, as this is identifying a >>> batch >>> of >>> calls. > >> How about log-id? >> It isn't supposed to be unique, or of any format, it's just used to >> log calls, so log-id is the most natural (or log-tag or whatever >> name you prefer). >> >> Also I think it's more of a header-type parameter since it's >> metadata for the call, not an actual parameter that influences the >> outcome of the "flow". > > I actually believe you're right, it probably is better to pass this parameter as > an http header. You've changed my mind about this (objections, anyone, to passing > it as a header as opposed to passing it as a url parameter)? Agree also that a header is much more natural in this case than a URL parameter. Also in the case where the client does not specify the ID themselves on the initial request, a generated value should be returned as response header (so that this can be passed as request header with the next request if part of the same over-arching task, or else just to aid log interpretation if the initial request was standalone but still mapped internally to multiple backend actions). > About log_id - it could sound like there are numerous logs, and the user is asked > to specify the ID of the log he wishes to write to. But perhaps: log_entry_id? Is there any possibility that this identifier may be leveraged for uses other than log interpretation? One other suggestion to add into the mix: MetaTask-ID.

No decision about the name of the parameter yet, and this is blocking me. Names that were suggested so far: * flow-id * batch-id * log_id / log_entry_id * op_id / operation_id

* correlation_id * MetaTask-ID It seems like the only purpose of this feature is logging, so I'm voting for 'log_entry_id' (although I consider some of the other options viable as well). Does someone disagree with 'log_entry_id'?

From the other options op_id/operation_id sounds best to me.

Thanks, Ori. ----- Original Message ----- From: "Itamar Heim" <iheim(a)redhat.com&gt; To: "Eoghan Glynn" <eglynn(a)redhat.com&gt; Cc: "Ori Liel" <oliel(a)redhat.com&gt;, engine-devel(a)ovirt.org Sent: Tuesday, May 8, 2012 12:40:25 PM Subject: Re: [Engine-devel] REST-API: Exposing correlation-ID On 05/08/2012 12:00 PM, Eoghan Glynn wrote: > > >>>>>> 1) what's the name you'd give this parameter? job-id? batch-id? >>>>>> flow-id? command-id? correlation-id??? >>>> >>>> job-id will confuse us with engine's job-id which is a single >>>> command >>>> today. >>>> correleation-id is pretty long and confusing as implies on >>>> correlation >>>> of something. >>>> >>>> I'm for flow-id or batch-id. >>>> batch-id sounds the right one to me, as this is identifying a >>>> batch >>>> of >>>> calls. >> >>> How about log-id? >>> It isn't supposed to be unique, or of any format, it's just used to >>> log calls, so log-id is the most natural (or log-tag or whatever >>> name you prefer). >>> >>> Also I think it's more of a header-type parameter since it's >>> metadata for the call, not an actual parameter that influences the >>> outcome of the "flow". >> >> I actually believe you're right, it probably is better to pass this parameter as >> an http header. You've changed my mind about this (objections, anyone, to passing >> it as a header as opposed to passing it as a url parameter)? > > Agree also that a header is much more natural in this case than a URL parameter. > > Also in the case where the client does not specify the ID themselves on the > initial request, a generated value should be returned as response header > (so that this can be passed as request header with the next request if part > of the same over-arching task, or else just to aid log interpretation if the > initial request was standalone but still mapped internally to multiple backend > actions). > > >> About log_id - it could sound like there are numerous logs, and the user is asked >> to specify the ID of the log he wishes to write to. But perhaps: log_entry_id? > > Is there any possibility that this identifier may be leveraged for uses other than > log interpretation? > > One other suggestion to add into the mix: MetaTask-ID. the one thing mentioned in the thread and worth remembering is this ID is not unique, as client can set it as they want. _______________________________________________ Engine-devel mailing list Engine-devel(a)ovirt.org http://lists.ovirt.org/mailman/listinfo/engine-devel

>> * MetaTask-ID -1, too pompous?

a maybe to remove the "ID" from name, since there is no uniqueness guarantee.

No decision about the name of the parameter yet, and this is blocking me. Names that were suggested so far: * flow-id

* batch-id * log_id / log_entry_id * op_id / operation_id * correlation_id

* MetaTask-ID It seems like the only purpose of this feature is logging, so I'm voting for 'log_entry_id' (although I consider some of the other options viable as well). Does someone disagree with 'log_entry_id'? Thanks, Ori. ----- Original Message ----- From: "Itamar Heim" <iheim(a)redhat.com&gt; To: "Eoghan Glynn" <eglynn(a)redhat.com&gt; Cc: "Ori Liel" <oliel(a)redhat.com&gt;, engine-devel(a)ovirt.org Sent: Tuesday, May 8, 2012 12:40:25 PM Subject: Re: [Engine-devel] REST-API: Exposing correlation-ID On 05/08/2012 12:00 PM, Eoghan Glynn wrote: > > >>>>>> 1) what's the name you'd give this parameter? job-id? batch-id? >>>>>> flow-id? command-id? correlation-id??? >>>> >>>> job-id will confuse us with engine's job-id which is a single >>>> command >>>> today. >>>> correleation-id is pretty long and confusing as implies on >>>> correlation >>>> of something. >>>> >>>> I'm for flow-id or batch-id. >>>> batch-id sounds the right one to me, as this is identifying a >>>> batch >>>> of >>>> calls. >> >>> How about log-id? >>> It isn't supposed to be unique, or of any format, it's just used to >>> log calls, so log-id is the most natural (or log-tag or whatever >>> name you prefer). >>> >>> Also I think it's more of a header-type parameter since it's >>> metadata for the call, not an actual parameter that influences the >>> outcome of the "flow". >> >> I actually believe you're right, it probably is better to pass this parameter as >> an http header. You've changed my mind about this (objections, anyone, to passing >> it as a header as opposed to passing it as a url parameter)? > > Agree also that a header is much more natural in this case than a URL parameter. > > Also in the case where the client does not specify the ID themselves on the > initial request, a generated value should be returned as response header > (so that this can be passed as request header with the next request if part > of the same over-arching task, or else just to aid log interpretation if the > initial request was standalone but still mapped internally to multiple backend > actions). > > >> About log_id - it could sound like there are numerous logs, and the user is asked >> to specify the ID of the log he wishes to write to. But perhaps: log_entry_id? > > Is there any possibility that this identifier may be leveraged for uses other than > log interpretation? > > One other suggestion to add into the mix: MetaTask-ID. the one thing mentioned in the thread and worth remembering is this ID is not unique, as client can set it as they want. _______________________________________________ Engine-devel mailing list Engine-devel(a)ovirt.org http://lists.ovirt.org/mailman/listinfo/engine-devel

----- Original Message ----- > From: "Itamar Heim&quot;&lt;iheim(a)redhat.com&gt; > To: "Eoghan Glynn&quot;&lt;eglynn(a)redhat.com&gt; > Cc: engine-devel(a)ovirt.org > Sent: Monday, May 14, 2012 7:07:07 PM > Subject: Re: [Engine-devel] REST-API: Exposing correlation-ID > > On 05/14/2012 07:05 PM, Eoghan Glynn wrote: >> >> >>>>> * MetaTask-ID >>> >>> -1, too pompous? >> >> Me, pompous? Never! ;) >> >>> a maybe to remove the "ID" from name, since there is no uniqueness >>> guarantee. >> >> Sure, MetaTask-Tag for example would be less connoting of >> uniqueness. > > I like 'Tag' > only problem is we have tags in the system already... > > looking for something in same area - how about just calling this > field > 'label' Agreed. I like Tag cause it's short... need to find something similar. cmd-id?

> >> >> But in general, I'd +1 any of the options that aren't suggestive of >> this being a purely log-oriented thing. >> >> Cheers, >> Eoghan > > _______________________________________________ > Engine-devel mailing list > Engine-devel(a)ovirt.org > http://lists.ovirt.org/mailman/listinfo/engine-devel >

On 05/14/2012 02:19 PM, Ori Liel wrote: > > No decision about the name of the parameter yet, and this is blocking me. > > > > Names that were suggested so far: > > > > * flow-id

Quite a few people liked flow-id, and no one objected to it explicitly, so I'll just go with that. If someone feels strongly against, please reply.

Ori ----- Original Message ----- From: "Michael Pasternak&quot;&lt;mpastern(a)redhat.com&gt; To: "Moti Asayag&quot;&lt;masayag(a)redhat.com&gt; Cc: "Ori Liel&quot;&lt;oliel(a)redhat.com&gt;, engine-devel(a)ovirt.org Sent: Monday, May 28, 2012 2:26:10 PM Subject: Re: [Engine-devel] REST-API: Exposing correlation-ID On 05/15/2012 05:31 PM, Moti Asayag wrote: > On 05/14/2012 02:19 PM, Ori Liel wrote: >>> No decision about the name of the parameter yet, and this is blocking me. >>> >>> Names that were suggested so far: >>> >>> * flow-id +1

On 28/05/12 21:31, Itamar Heim wrote: > On 05/28/2012 02:35 PM, Ori Liel wrote: >> Quite a few people liked flow-id, and no one objected to it >> explicitly, so I'll just go with that. >> >> If someone feels strongly against, please reply. > > I still like 'label' better. > it doesn't have the context of a unique id, and is much more correct to > what this is - allows the user to label a command (or a set of commands). > but also doesn't imply it's unique in any way (i.e., it's like a "tag", > just a better, non overloaded term for it). > I think that flow-id is confusing. This id has nothing to do with flow, it can aggregate multiple commands and it is not associated with a specific user flow. Correlation-Id is a common name for such Id, we took it from the terminology used in JMS queues, but Microsoft and Oracle are using CID too. * http://www.microsoft.com/en-us/download/details.aspx?id=23842 * http://sharepoint.microsoft.com/blogs/GetThePoint/Lists/Posts/Post.aspx?I... * http://docs.oracle.com/cd/B14099_19/integrate.1012/b25709/com/oracle/bpel...