[Engine-devel] REST-API: Exposing correlation-ID

[Ori Liel]

----- Original Message -----
From: "Itamar Heim" <iheim at redhat.com>>
To: "Eoghan Glynn" <eglynn at redhat.com>>
Cc: "Ori Liel" <oliel at redhat.com>>, engine-devel at ovirt.org
Sent: Thursday, May 3, 2012 7:10:32 PM
Subject: Re: [Engine-devel] REST-API: Exposing correlation-ID

On 05/03/2012 06:15 PM, Eoghan Glynn wrote:
>>
>>
>>> 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.
>
>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