TelemetryClient.trackRequest should allow telemetry with id property

TelemetryClient.trackRequest and Telemetry.trackDependency should allow the ‘telemetry’ object to have an ‘id’ property. The method signatures should be:

public trackRequest(telemetry: RequestTelemetry & Identified): void 

public trackDependency(telemetry: DependencyTelemetry & Identified): void

This is required if the caller wants to set the Contracts.RemoteDependencyData.id and Contracts.RequestData.id properties which get set during the following EnvelopeFactory methods:

https://github.com/Microsoft/ApplicationInsights-node.js/blob/7a6357b8c75fa419dc6842c1bce80933bc2aa489/Library/EnvelopeFactory.ts#L171

https://github.com/Microsoft/ApplicationInsights-node.js/blob/7a6357b8c75fa419dc6842c1bce80933bc2aa489/Library/EnvelopeFactory.ts#L115

[tmcgannon]

I do not use the applicationInsights.setAuto* methods - they do capture the data we are most interested in, they do not make the correct correlations (i.e. Request->Dependencies->Dependencies->Events, Exceptions), they do not handle WebSocket requests which we use almost exclusively (no HTTP requests), and we already keep our own context object that lives throughout the lifespan of a WebSocket request.

The auto correlation/collection features in your library make huge assumptions that every node developer is using a standard Express infrastructure. In my opinion, you should have a low level interface for devs like me that gives full access to the features of AI, and a high level interface (like the one you have implemented) for people who just want to write a few lines of code and get some value from AI.

There is way too much automagical behavior happening in this library. When I did my original testing, most of the auto features did not work as I expected and was void of any meaningful documentation - I had to read the code to figure out what was going on. Now that you refactored the code in v0.22, I no longer had access to the Contracts interfaces and am trying to work within your new Telemetry interface. [BTW, all of the *Telemtry.d.ts interfaces are not exposed so you cannot, for example, define a variable as a EventTelemetry (in TypeScript), populate it, pass it as a parameter to a method that eventually calls TelemetryClient.trackEvent(). Instead, you have to call TelemetryClient.trackEvent() with a JS object literal that specifies all of the fields. Please expose the *Telemtry.d.ts interfaces.]

Let me know if you need more reasons why I’m not using the “internal” features of this SDK.

[OsvaldoRosado]

Thanks for the explanation!

they do not make the correct correlations (i.e. Request->Dependencies->Dependencies->Events, Exceptions)

I would love to hear more about what the SDK does here that is incorrect. Correctness in correlation is very important!

The auto correlation/collection features in your library make huge assumptions that every node developer is using a standard Express infrastructure.

It goes a little bit deeper than that, we monitor http.createServer so even non-Express libraries should still work. It does however only support HTTP-based servers. Autocollection for things like WebSockets is tricky as WebSocket operations don’t necessarily have clear, expected, analogs in our telemetry schema. This is exactly why we expose the TelemetryClient API - so we can make these optional assumptions for the most common case, and allow manual instrumentation in scenarios we can’t handle automatically.

In my opinion, you should have a low level interface for devs like me that gives full access to the features of AI, and a high level interface (like the one you have implemented) for people who just want to write a few lines of code and get some value from AI.

I’m interested to know which functions you’d like to see us make available for manual use. Across our supported platforms (.NET, Java, etc.) the TelemetryClient interface is our standard API, but I’m interested in useful functions that this is missing.

There is way too much automagical behavior happening in this library. When I did my original testing, most of the auto features did not work as I expected and was void of any meaningful documentation - I had to read the code to figure out what was going on.

I share these concerns. Documentation is something we’re working on improving, as well as making the magic more open - especially around correlation in non-HTTP environments.

I no longer had access to the Contracts interfaces

These should still be available at appInsights.Contracts please let me know if this isn’t working for you! That would most certainly be a bug.

all of the *Telemtry.d.ts interfaces are not exposed so you cannot, for example, define a variable as a EventTelemetry (in TypeScript), populate it, pass it as a parameter to a method that eventually calls TelemetryClient.trackEvent()

Great catch! These are exactly the kinds of problems we were hoping to track down with this first release of the new API format. These types perhaps should move into Contracts or its own first level export on appInsights. I think this wasn’t caught as the intention was they would be used just like the previous function parameters were, which, of course, can’t be built up separately from the function call.

Let me know if you need more reasons why I’m not using the “internal” features of this SDK.

My question is still specifically over the necessity of setting the envelope id property. Is this issue that there’s no good way to read what it will be set to in order to manually set later parentId values for correlation in child telemetry items? I think the inner machinery into how correlation works is very easy to get wrong (and in flux from time to time!)

Perhaps a function to generate a new correlation context with a specified root identifier is the way to go here? Being able to set the initial values and letting the SDK do the appropriate logic to generate a hierarchical id sounds like the right balance here - it’s quite a bit to be asking an SDK user to do themselves in manual scenarios. A manual function here also has the nice benefit of allowing you to benefit from dependency correlation even in a non-HTTP scenario where you’re missing the wrapper to automatically start the correlation context.

As for a workaround in the current SDK release, the simplest thing to do is supply the id you want to use instead within the contextObjects parameter at track time. With this, you can write a simple telemetry processor that will read this value and set it to the envelope.id field (Telemetry processors still operate on the root internal telemetry contracts and can thus make this adjustment) Does this work for you?

Thanks again for the feedback!