Skip to content

SAP Passport Support

SAP Passport is a correlation mechanism that uniquely correlates requests and message artifacts with end-to-end requests and message flows.

The SAP Passport instrumentation provides the foundation for different use cases:

  • Metering: Distinguish between SAP-to-SAP and non-SAP-to-SAP communication. SAP management has directed that the capability to identify uniquely whether SAP components are indirectly accessed by non-SAP components be available. Each component (including SAP partner products) that implements the SAP Passport is considered to be an SAP internal component (SAP-to-SAP communication). Components that do not have Passport implemented are considered to be SAP external components, which therefore qualify for the indirect billing use-case.

  • Integration Monitoring: In complex business scenarios, as supported by the Intelligent Suite, containing a variety of cloud services and systems, integration plays a crucial role. As more components become involved, the need to exchange master and transactional data becomes more crucial. Data transfer always leads to technical and business exceptions, which need to be handled by operation teams both at the customer location and at SAP. With the cloud-based operation platform, we provide SAP Cloud ALM for Operations (CRUN) and the on-premise-based operation platform Focused Run for SAP Solution Manager (FRUN) central applications for integration monitoring. Integration monitoring supports monitoring of peer-to-peer interfaces (direct calls), as well as orchestrated interfaces (message flows) with unified user experience.

  • User Monitoring: As more components become involved, it becomes more difficult to understand how a single user activity is processed. If end user performance is unsatisfying, it is key to identify the cloud or on-premise component that is causing the issue. To this end, we need to sufficiently correlate the different user request artifacts.

  • End-to-End Tracing: On top of the integration and user monitoring use case, it may be relevant to enable for root cause analysis, tracing of single requests or messages. Here, the SAP Passport provides sufficient support. Depending on the trace flags, which are transported as part of the SAP Passports, traces are dynamically switched on in the receiving component. This allows tracing single requests or messages without influencing the overall stability or performance of the involved productively used components.

  • Business Process Monitoring: From an instrumentation perspective, this is more complex as the “technical” SAP Passport is relevant for the use cases mentioned above. This is beyond the current implementation scope.

Note

The default scenario is Metering.

Implementation

A passport has six configurable attributes/fields: Trace Flag, Component Name, User ID, Action, Previous Component Name and Component Type.

The default values for these attributes is shown below:

Attribute Default Value
Trace Flag TRCLVL_LOW
Component Name "Android SDK " + SDK_VERSION
User ID "dummy"
Action "HTTP_Request"
Previous Component Name "Android SDK " + SDK_VERSION
Component Type TRACELIB

Note

By default, the SDK does not include the user name due to data regulation and privacy implications. In essence, User ID will not be modified and will keep the default value. Developers may set this field but should be aware that this requires explicit user consent in many countries.

You can choose other optional values for Component Type and Trace Flag, and set reasonable values for the other four attributes.

However, different attributes are used by different use cases. Thus, different passport builders are provided: MeteringPassportBuilder, IntegrationMonitoringPassportBuilder, UserMonitoringPassportBuilder, E2ETracingPassportBuilder and BusinessProcessMonitoringPassportBuilder. That is to say, some fields are configurable in one builder but may be not configurable in another builder.

Note

There is also a Passport class, which could be customized to set all six configurable attributes in certain special scenarios.

Passport and PassportHeader are managed by PassportManager.

Build Passport

Recommended method: Use one passport builder for your use case.

Passport passport = new MeteringPassportBuilder()
        .setComponentName("component")
        .build();
val passport = MeteringPassportBuilder()
        .setComponentName("component")
        .build()

Customized way: Use Passport class to create a passport.

Default passport (for Metering):

Passport passport = new Passport();
val passport = Passport()

Passport with specific attributes value:

Passport passport = new Passport(TraceFlag.TRCLVL_LOW, "component name", "dummy", "HTTP_Request", "previous component name", ComponentType.TRACELIB);
val passport = Passport(traceFlag = TraceFlag.TRCLVL_LOW, componentName = "component name", userID = "dummy", action = "HTTP_Request", prevComponentName = "previous component name", componentType = ComponentType.TRACELIB)

Get Passport

PassportManager.INSTANCE.getPassport();
PassportManager.passport

Set Passport

PassportManager.INSTANCE.setPassport(newPassport);
PassportManager.passport = newPassport

Update Passport Fields

Passport passport = PassportManager.INSTANCE.getPassport();

Passport newPassport = new MeteringPassportBuilder(passport)
        .setComponentName("new component name")
        .build();
val passport = PassportManager.passport

val newPassport = MeteringPassportBuilder(passport)
        .setComponentName("new component name")
        .build()

Another easier way to update certain passport fields for Kotlin is:

val passport = PassportManager.passport

val newPassport = passport.copy(componentName = "new component name")

Get PassportHeader

A passport header is a string converted from a complete passport that will be sent to the server with requests.

String header = PassportManager.INSTANCE.getPassportHeader();
val header = PassportManager.getPassportHeader()

Last update: September 29, 2020