Using Tracing APIs in Standalone SUPSupportability Library

• Creating a Passport:
  A passport is a string of encoded parameter values used in controlling logging information and taking logging decisions across various components in server and client runtime. The passport is used to log debugging information as directed by the passport configuration.

  Components of Passport

  Component	Description
  Root Context Id	A unique ID that represents a client/application. This ID should be same for all generated passports in a tracing session.
  Transaction Id	An ID that represents a transaction (one cycle of request-response) performed by the client or application. This is useful for tracking a request end-to-end. A new transaction ID should be created for each new request.
  Trace Level	The trace level controls what and how much should be logged. The trace level can be set to HIGH, MEDIUM, or LOW. Note: The trace level is always specified by the administrator.

  Note: It is mandatory for the client application to include a passport with communication to the server and each and every component in the server execution path.
• Business Transaction XML Creation:

  The Business Transaction XML (BTX) contains the client side trace which includes the client-server communication trace (request-response), as well as, the other trace generated by various execution points/entities in the application. The BTX creation starts when the application starts a tracing session and stops when the trace session is ended.

Usage

1. Enable end to end tracing

   The following code illustrates how to start the Business Transaction XML creation.

   //Get a handle to the BTX writer and do required initialization steps
    com.sap.smd.e2e.trace.bustrans.impl.TraceController  traceController = com.sap.smd.e2e.trace.bustrans.impl.TraceController.getInstance();
   
   //set the trace level we are going to use for the passport. could be obtained as passport.getTraceFlag() if the passport is already available
    
    traceController.setTraceFlag(<trace level int value>);
   
   //set the deviceId which will be used for identifying the BTX specific to a device.
    traceController.setDeviceId(deviceId);
   
   //Inform the trace controller to start the trace session and initialize BTX creation. Specify the application name/id as BTX name. appName is used to identify an application specific BTX on the Solution Manager.
   
    traceController.startTransactionResult(appName);
   
   Note:
   ‘appName’ is the SAP Mobile Platform Application Id.
   ‘deviceId’ can be obtained from the http response (to the device registration request) cookie with key as ‘X-SUP-
    APPCID’.
   ----------------------------------------------------------------------------
   

2. Trigger end to end trace, create an instance of SAP Passport.

   com.sap.smd.e2e.trace.passport.IPassport passport = com.sap.smd.e2e.trace.passport.PassportFactory.createPassport();
   
   com.sap.smd.e2e.trace.passport.IGuid transactionId = com.sap.smd.e2e.trace.passport.GuidGenerator.generateBusinessTransactionId();
   passport.setTransactionId(transactionId);
   
   passport.setRootContextId(traceController.getRootContextId());
   
   passport.setTraceFlag(com.sap.smd.e2e.trace.passport.DsrUtils.TraceFlags.TrcLvl_LOW);  //similarly TrcLvl_MEDIUM and TrcLvl_HIGH could be used as required.
   
   //Get the encoded passport string
   String encodedPassport = passport.getEncoded();
      

   Note: Create a new passport for every new request that the application makes to the server. Add the encoded passport string to the request headers with key as SAP-PASSPORT. This is required to uniquely identify or track a request end to end.
3. Add the request-response traces to the Business Transaction XML.

    //Create a transaction message using the various request-response parameters
   and pass it to the BTX writer  
     
   com.sap.smd.e2e.trace.bustrans.IRequest request = new com.sap.smd.e2e.trace.bustrans.impl.Request();
   
   //SAP-PASSPORT and X-SUP-APPCID headers need to be set into the  trace request along with other headers. SAP-PASSPORT will be the same  passport used in the request headers (to server). X-SUP-APPCID is the device ID or application connection ID
   available in device registration response cookie.
   request.setHeaders(<Request Headers>);
   request.setContent(<Request Line>);
   request.setSentBytes(<number of bytes sent>);
   
   com.sap.smd.e2e.trace.bustrans.IResponse response = new com.sap.smd.e2e.trace.bustrans.impl.Response();
   response.setHeaders(<Response Headers>);
   response.setContent(<Response Data>);
   response.setResponseCode(<response code>);
   response.setReceivedBytes(<number of bytes received>);
          
   traceController.createStep(request);
   
   //Note: The following is a mandatory and important step which ties a transaction step(request) with a transaction ID.
   //Since we create a new passport for a new request and set a transaction ID for the passport every time, it is good to use the same
   transaction ID here for better correlation
   
   traceController.addTransactionId(request, passport.getTransactionId().getHex()); //the transaction id used in the passport generated for current request.  
   
   //Add these collected transaction (request-response details/statistics) to the BTX document
   traceController.addMessage(request, response, firstByteSent, lastByteRcvd);
   

4. Stop or disable end to end tracing

   The following code illustrates how to stop the Business Transaction XML creation.

   traceController.stopTransactionResult();

5. Get the generated Business Transaction XML.

   byte[] btx = traceController.getTransactionXML();
   // Client application can save this byte array into a file that can be uploaded

6. Upload Business Transaction XML to Solution Manager.
   Note: For more information, see the Uploading Business Transactions for Tracing in Developer Guide: REST API Applications.