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()