Define wcf attributes & spans

[thompson-tomo]

Area(s)

area:rpc

What's missing?

The wcf implementation https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Wcf/Implementation/ClientChannelInstrumentation.cs to be following semconv. The implementation can be updated

Describe the solution you'd like

Introduction of the wcf namespace which contains the necessary attributes for the definition and the spans rendered in a dedicated doc.

Key new attributes being:

• wcf.request.header
• wcf.request.property
• wcf.response.header
• wcf.response.property

Solution for SOAP version

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[KalleOlaviNiemitalo]

In WCF, identifiers of message headers are XML qualified names like in SOAP, consisting of a local name and a namespace URI. Do you have ideas for how those would be represented?

I'm also interested in representing SOAP 1.2 fault codes in the error.type attribute or in some SOAP-specific attribute. In the latter case, it could be an array in which each element corresponds to a nested fault code.

I'd omit properties of WCF messages from the semantic conventions. They are generally not transferred over the wire, they may contain non-serialisable objects, and they may be modified during message processing. If a WCF response message has an HttpResponseMessageProperty, its contents can be instead mapped to the HTTP semantic conventions.

[thompson-tomo]

@KalleOlaviNiemitalo thanks for your input.

In WCF, identifiers of message headers are XML qualified names like in SOAP, consisting of a local name and a namespace URI. Do you have ideas for how those would be represented?

I would have it as an opt-in templated attribute like headers in http.

I'm also interested in representing SOAP 1.2 fault codes in the error.type attribute or in some SOAP-specific attribute. In the latter case, it could be an array in which each element corresponds to a nested fault code.

I see those fault details as being the body of an event. But yes the soap fault codes should be mapped in a similar manner to other rpc.systems.

I'd omit properties of WCF messages from the semantic conventions. They are generally not transferred over the wire, they may contain non-serialisable objects, and they may be modified during message processing. If a WCF response message has an HttpResponseMessageProperty, its contents can be instead mapped to the HTTP semantic conventions.

This would also be an opt-in templated attribute.

[KalleOlaviNiemitalo]

Some message properties defined by WCF have rather long names:

• ImpersonateOnSerializingReplyMessageProperty
• System.ServiceModel.Channel.MtomMessageEncoder.WriteMessageHeaders
• System.ServiceModel.Channels.RemoteEndpointMessageProperty
• System.ServiceModel.Discovery.DiscoveryMessageProperty

Prepend wcf.response.properties. to those and you can get 90 characters. Is there a limit on the length of attribute names? I don't see any at https://opentelemetry.io/docs/specs/semconv/general/naming/.

[thompson-tomo]

I am not aware of a limit. Note it would be up to the instrumentation to determine the custom key part of the attribute key. The attribute is intended for https://learn.microsoft.com/en-au/dotnet/api/system.servicemodel.channels.message.properties?view=netstandard-2.0-pp rather than any property in the exchange.

[joaopgrassi]

@lmolkova @trask can you please give this a look and see if it contains all details needed to classify it as "ready"?

[KalleOlaviNiemitalo]

@thompson-tomo, re templated attributes, do you intend to make any recommendation on what keys to use in the templates?

For example, [MS-NETTR]: .NET Tracing Protocol §4.1 Sample SOAP Messages shows a SOAP message with this header:

<ActivityId CorrelationId="7224e2a9-8f9c-4acb-a924-17cb6af67b23"
 xmlns="http://schemas.microsoft.com/2004/09/ServiceModel/Diagnostics">
       43ffa660-a0c6-4249-bb36-648b73a06213</ActivityId>

Would it be OK for an instrumentation to translate that to two attributes

name	type	value
wcf.request.headers.ms-nettr.activity	string	43ffa660-a0c6-4249-bb36-648b73a06213
wcf.request.headers.ms-nettr.correlation	string	7224e2a9-8f9c-4acb-a924-17cb6af67b23

or would the semantic conventions require that the instrumentation translate this header to only one attribute, and include the ActivityId element name in the attribute name somehow?

[thompson-tomo]

A recommendation/pattern on how to define nested properties and also nested objects would be needed.

In your scenario I would expect to potentially end up with:

• wcf.request.header.ActivityId
• wcf.request.header.ActivityId:CorrelationId

Guideline could be:

• | for nested objects
• : for nested properties

[KalleOlaviNiemitalo]

How about that xmlns="http://schemas.microsoft.com/2004/09/ServiceModel/Diagnostics" then; what if there is another ActivityId header in a different namespace and the instrumentation wants to translate that to an attribute as well?

[thompson-tomo]

In that case perhaps the guideline should be:

• / for nested objects
• | for nested properties
• : to seperate namespace name & property name

That way for the below message

<soapenv:Envelope 
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:ns1="http://example.com/namespace1" 
    xmlns:ns2="http://example.com/namespace2">
    
    <soapenv:Header>
        <ns1:AuthHeader>
            <ns1:Username>exampleUser</ns1:Username>
            <ns1:Password>examplePassword</ns1:Password>
        </ns1:AuthHeader>
    </soapenv:Header>
<soapenv:Envelope>

You could have the following attribute key

• wcf.request.header.ns1:AuthHeader/ns1:Username

It might be necessary to also have

• wcf.request.namespace.ns1 etc to provide context

And for your original example:

• wcf.request.header.ActivityId
• wcf.request.header.ActivityId|CorrelationId

[KalleOlaviNiemitalo]

IIRC, WCF writes thexmlns:* attributes in the elements where they are needed, rather than immediately at the SOAP Envelope element. So you can have different meanings for ns1: in different headers of the same SOAP message, or even in different elements of the same header. From this, it follows that the instrumentation might only be able to translate the first occurrence of xmlns:ns1 to wcf.request.namespace.ns1 and might have to choose different telemetry attribute names for other occurrences. Then if a user has exported this telemetry to an analysis service and wants to query the collected data for a SOAP header with a specific (XML namespace, local name) combination, are query languages able to do that or do they require static names for the attributes?

I feel that defining an all-purpose attribute template for SOAP headers in WCF is a misguided effort and one should instead define specific attributes for specific headers.