25 Diagnostics

The Diagnostics features of OMCe provide live performance data and quick access to detailed log messages for each API and connector request. If you are an administrator, you can use these features to monitor performance and error rates and to debug any problems that arise. If you are a developer, these features help you debug your code.

What Can I Do with Diagnostics?

Whether you’re a developer tracing errors in custom code, or an administrator who notices a flurry of 5xx responses, Diagnostics lets you easily find out what’s going on by providing you with increasingly detailed levels of logging messages.

The Diagnostics landing page provides a high-level view that includes a traffic-light indicator that conveys overall environmental health, a timeline that plots requests and responses, and also counters to tally the failing requests resulting in HTTP 4xx and HTTP 5xx errors. This page provides the entry point to more detailed levels of analysis, because you can drill down from an indicator or an error counter to identify which requests are failing and view log records that are associated with them. To see specific logs, check out Viewing Underperforming Requests.

Although admins and developers can both benefit from diagnostics, each uses it differently. As pointed out in Monitoring Environments for a Selected Mobile Backend, developers typically use a backend’s diagnostics as the starting point in their debugging efforts. To get an idea how developers go through their paces see Use Case: Using Correlation to Diagnose Custom Code. While developers focus on a backend, administrators instead monitor the big picture for a system. For an example of how an administrator goes from this page to access logging data, see Use Case: Using Correlation to Diagnose Connector Issues.

Viewing Environment Health

The green, amber, and red traffic light indicators on the Diagnostics page depict the overall health of an environment for the last hour, or other selected time period.

Description of the illustration diagnostics_landing_page_-severe.png

OMCe bases this at-a-glance view on the fine-grained health metrics for that environment. When the percentage of error responses exceed configured thresholds for the selected time period, the traffic light indicator changes from green (normal) to amber (warning) or red (severe).

The time period for analysis can be changed using the menu, with additional choices for 2, 6, 12, or 24 hours.

Viewing Server Load

As part of the overall portrait of health at any given moment, the Diagnostics page includes a timeline that plots a recent history of the number of requests and response times.

Viewing Errors

The Diagnostics page notes the number of client (4xx) and server (5xx) errors that have occurred within the last hour or other selected time period. See Viewing Status Codes for API Calls and Outbound Connector Calls.

Viewing Underperforming Requests

The high-level data shown on the Diagnostics page is the entry point for increasingly detailed levels of analysis. When you hover over an indicator, the traffic light indicator shows the percentage of failed requests. This data is derived from the last hour or other selected time period of the system's behavior and highlights the severity of an issue by color, from green (healthy) to red (severe). From here, you can evaluate the root cause by clicking the traffic light to investigate problematic requests or APIs, and by viewing the API history log data to get a breakdown of the requests and any child requests. See also Viewing Log Messages Related to a Request.

Viewing Log Messages Related to a Request

Rather than using various grep commands to find log records between time stamps in the logs, OMCe uses correlation to associate log messages to a specific API request to help you locate the pertinent records from the API request history. If you're troubleshooting, correlation lets you quickly find the root cause by presenting detailed information, such as invalid JavaScript code or an unavailable resource called by a connector. See Relating Log Messages. For more information about the various logs generated by Diagnostics (such as the API History, Connector History, Custom Code, and System logs), see Viewing Log Messages.

Viewing Storage Usage

In addition to showing API request data, the Diagnostics page shows you how much database storage, shown in gigabytes, the environment is currently using. You can see this information in the top right corner of the page.

Monitoring a Selected Backend

The backend’s summary page gives you a snapshot of the current health of its environment. You can take a deeper look at request and response processing and error handling by selecting the backend and then clicking Open.

Description of the illustration mbe_summary_external.png

The Diagnostics page displays the number of the requests and responses, plots them on a timeline, and notes the number of client and server (4xx and 5xx) errors. Because this page gives you a snapshot of the overall health of a backend, you can focus your attention where it's needed: on specific performance issues or problems with the API implementations and connectors used by the backend.

Description of the illustration diagnostics_dash_external.png

While you can drill down through the Overview page to specific endpoint data, you can also view detailed API request and error information using the Health, Request History, and Logs pages.

Viewing API Performance

You can find out how the performance of a specific API contributes to the overall health of a backend or to an entire environment. For each API, OMCe records the same error and request handling metrics that it applies to a backend. You can drill down to see how the API endpoints behave in terms of these performance metrics.

From Diagnostics, click Health to view the APIs for a backend . You can also open this page by clicking the traffic light indicator on the Diagnostics page. If the traffic light indicator is amber or red, then you can quickly investigate the cause of the problem by using the Health page.

Description of the illustration diagnostics_health_drill_down.png

Adjusting the Performance Threshold Configurations

The default thresholds may not apply at all phases of the backend's lifecycle and may not always reflect your interpretation of a healthy environment. To adjust the thresholds, administrators can get the policies file that contains the default configurations by clicking Export. After they adjust the thresholds, they can import the file by dragging it into the Policies pane.

Description of the illustration policies_window.png

For more information on policies, see Oracle Mobile Cloud Enterprise Policies.

Viewing Status Codes for API Calls and Outbound Connector Calls

When you open the Request History page, its 4xx and 5xx status code buttons are selected by default, displaying the client (4xx) and server (5xx) HTTP status codes for the API's endpoints and the outbound connector calls made within a single backend (if you're a developer) or across all backends (if you're an administrator). This page gives you a glimpse into the context of the status code, letting you trace the causes for various status codes.

Description of the illustration diagnostics_log-entries_related_to_a_request.png

The Request History page displays a time stamp that indicates when the connector or API request was made and the resulting status code.

Tips:

• Clicking the time stamp opens the message itself.
  
  See Viewing Message Details

You can learn more about the API call or outbound connector request by looking at the page's Call and Path columns, which show you a description of the targeted resource as well as the action and object of the request.

The table that lists the calls displays the sizes of the request and response in bytes as well as the response time. If a slow response time might indicate a problem, then you can troubleshoot the issue using correlation. See Viewing Log Messages Related to a Request.

Request Type	Content Displayed in the Call Column	Content Displayed in the Path Column
API requests that are returned 200 (Success)	The backend name, version > API name and version. For example: FiFTechnician 1.1 > FiFReports 1.1	The HTTP method with the resource path. For example: GET /reports/{report}
API requests that are returned 5xx (Unserviceable Requests) status codes	The backend name, version > API name and version (if available); otherwise this column is blank. FiFCustomer 1.0 > incidentreports	The HTTP method and information about the resource path. For example: POST /contacts
Outbound Call from a SOAP Connector	The endpoint URL, such as: http://myhost.us.example.com:7002/mobilesvc/IncidentService	The operation name. For example: GET /incidents/{id}
Outbound Call from a REST Connector	The host, such as:maps.somecompanyapis.com	The method with the resource path.

You can filter the display of error messages using any combination of the page's status code buttons and sort them in chronological or reverse-chronological order. While the default 4xx and 5xx buttons are toggled by default to display error codes, you can also view messages for informational (1xx), success (2xx) and redirection (3xx) codes. Common 4xx and 5xx codes include:

• 400 - Bad Request

• 404 - Not Found

• 408 - Request Time Out

• 500 - Internal Server Error

• 501 - Not Implemented

• 503 - Service Unavailable

  For a complete list of HTTP status code definitions, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

Relating Log Messages

For each request, you can use correlation to get the logging data to a request by using the options in the Related Logs column. You can correlate log records by app session, mobile device, user, and API request.

Description of the illustration sel_related_log.png

To query a list of log records that are tagged with the correlation ID for the request, select Log Messages Related by API Requests. After you select this option, the Filters field is populated by the request's correlation ID. The messages displayed in the Logs page were generated during the servicing of the request.

Tip:

You can also generate a list of request-related messages by clicking the funnel next to Request Correlation ID in the Message Details page. See Viewing Message Details.

This ID provides additional correlation when you use the Oracle stack. For example, if you run systems on Oracle Fusion Middleware and use connectors to communicate with those systems, then all of the requests made will use the same correlation ID and can therefore be correlated with requests to the OMCe server. See Diagnosing Custom Code.

How Client SDK Headers Enable Device and Session Diagnostics

When you use the client SDK for your mobile platform in your apps, the SDK injects the mobile diagnostic session ID (M_DSID) into request headers. Because the client SDK is optional, app developers can override this behavior by setting their own headers.

The Oracle-Mobile-DEVICE-ID and Oracle-Mobile-SESSION-ID headers, described in SDK Headers, enable Diagnostics to correlate records when you select the Log Messages by Mobile Device and Log Records by Mobile App Session options. While the server automatically generates the correlation ID for each request, the mobile app adds diagnostic capabilities by providing the session and device IDs. App developers can define how sessions are expressed. For example, they can group requests as a single session. App developers can also define the device ID to distinguish requests. A device ID isn’t the device manufacturer ID, but rather an ID assigned by the developer to the user’s device.

Note:

A single user can operate multiple devices that run the same app. The app may exhibit problems on only one of the devices.

Administrators can use this ID to differentiate a request message that’s specific to an app user’s device amid thousands of other messages. Without this header, administrators can still correlate records by a user because users are established through authenticated requests.

Viewing Log Messages

You can access this page by selecting from the logging options in the Related column in the Request History page, or by clicking Logs on the top-level health page.

If you're an administrator, then view the logging data by either drilling down from the Related column in the Errors page or by clicking Logs in Diagnostics. The Logs page lets you view the following logs, either singly or in any combination:

• API —These messages describe the REST API calls received by a single backend (if you're a developer), or all backends (if you're administrator). These messages are logged in the API History log. See Taking a Look at Exported Messages.

• Connector—These messages describe the outbound calls made by the connectors to SOAP or REST endpoints. These messages help you to troubleshoot problems arising from incorrect connector and endpoint configurations as well as those related to the downstream resource itself (connection timeouts, service unavailable, or other situations that result in 5xx status code messages). See Connector Message Details.

• System log—These messages can describe a general problem encountered by OMCe (for example, it can't send notifications to providers like Apple Push Notification Service or Google Cloud Messaging) as well as the cause of the problem (such as an incorrect configuration that prevents a mobile app from sending notifications).

• Custom Code—These messages describe the issues logged through the custom code service container. These messages include the ones that are generated by the custom code service itself about the starting and stopping of the Node.js instance and messages created by service developers using the Node.js' console object.

In addition to the log buttons, you can view the log messages by date using either the presets or the date editor.

You can also apply filters, so that you can view messages by message type, backend, backend version, and API name. You can add filters by selecting from the drop down list, or by entering some criteria in the Filters field. For example, if you're interested in a particular backend, then enter its name in the Filters field.

Tip:

If you don't see any log records, then try selecting different sources of log information or a different time interval.

The Logs page lists the log messages by time stamp. Just as you could on the Request History page, you can view the log message by clicking the time stamp.

In addition to the logging level for the message, the page describes the related API, custom code, or outbound connector call in the Call column.

You can retrieve specific error messages by entering terms in the Message Text field, then clicking Search.

The Logs page displays up to 500 records. If your query returns more than 500 records, click Export to transfer all of the logging data to a local file that’s formatted in CSV, JSON, text, or XML. The export is restricted to 10,000 log records. See Taking a Look at Exported Messages.

Viewing Message Details

To find out more about a request, review the API history message by clicking the time stamp.

The API history message has two tabs: Overview and Headers. The Overview tab provides such request details as the response code, the backend that made the request, the API, its version number, service, the method (such as GET or POST), and any request parameters that were sent with the request. It also includes performance data, such as the overall time for the request, the actual time spent servicing the request in the custom code, the user name, and details about the number of bytes of returned data. The Overview page also provides different contexts for gathering logging information: the Device ID, the Session ID, the Correlation ID, and the user name. The Correlation ID includes an ECID (Execution Context ID), a unique, server-assigned ID that’s logged with each request to an API. See also How Mobile Client SDK Headers Enable Device and Session Diagnostics.

Description of the illustration message_details_ov.png

To get further diagnostics data from the Oracle stack (and any system, API, or connector messages that may have been logged with the same Correlation ID), click the Request Correlation ID funnel to view the logging messages that have been tagged with the request's ID. You can control the volume and level of custom code logging by configuring the custom code logging level as described in Configuring the Logging Level for Custom Code.

Clicking the Headers tab gives you information about request and response headers.

Description of the illustration message_details_hd.png

Taking a Look at Exported Messages

Exporting log files to a local file provides a set of logging data in addition to the information displayed in the Details pages.

Description of the illustration export_as_text_external.png

API Request Messages

Along with a brief description, each request message has the following attributes:

Attribute Name	Description
Time	The time corresponding to the REST API event.
Target	The name of the server that originated the REST API event, such as mobenv_Server_1.
Message Level	The message log level, such as NOTIFICATION.
Message ID	An ID for the message, or corresponding event type. For example, MOBILE-38594.
userId	The user identifier. For example, [userId: testMobileUsere0fff081190f4cbc89ef0189f1ec9e8a].
Module ID	The ID of the module that logged the message, such as oracle.cloud.mobile.APIHistory.
Thread ID	The Java thread in which the request is dispatched by the OMCe core runtime. For example, tid:61.
ECID	The execution context in which the request has been dispatched by the OMCe core runtime.
RID	The Relationship ID of the execution context. The RID tracks any subrequests called by the OMCe services.

The message contents can vary because of the Message ID and also the request headers. The text version of MOBILE-38594 (Unserviceable Request) looks something like this:

[2015-01-20T22:35:37.848+00:00] [mobenv_Server_1] [WARNING] [MOBILE-38594]
[oracle.cloud.mobile.ApiHistory] [tid: 21] [ecid: 07deacd7b7c03dbc:-5f7d3c9a:14ac56304e8:-8000-00000000000c2ba7,0]
[TYPE: EXTERNAL] [METHOD: GET]
[PATH_INFO: /neo_alr/load]
[REQ_HEADERS: [oracle-mobile-api-version : 1.1], [Host : us.example.com:7001], [Accept-Encoding : gzip], [User-Agent : Java1.7.0_51], 
[Connection : Keep-Alive], [Accept : text/html, image/gif, image/jpeg, */*; q=.2]]
[REQ_PARAMS: [x : /home/paasusr/intercept.sh 50581 127.0.0.1 50580 2>&1 > /tmp/i.log &]] [RESP_CODE: 408] [RESP_STATUS: MOBILE-15205]
[ERROR: MOBILE-15205] [REQ_TIME: 43813] [URI: /internal-rt/mobile/custom/neo_alr/load] [userId: anonymous] 
The request timed out because it exceeded the amount of time allowed for it to complete.
[[Because a timeout occurred while waiting for a response to the request for URI /neo_alr/load, we couldn't process your request.
You can find more details in the system log.]]

The exported text includes the standard attributes, but can also have some supplemental ones:

Attribute Name	Description
TYPE	The type of the request, which is either EXTERNAL or INTERNAL. Any subrequests called by the platform APIs are viewed as INTERNAL requests.
ENV_NAME	The environment name of the REST API.
METHOD	HTTP request method: GET, PUT, UPDATE, DELETE.
MB_NAME	The name of mobile backend. For example, [MB_NAME: FixItFast-Technician].
MB_VERSION	The version of the mobile backend. For example, [MB_VER: 1.0].
REQ_PARAMS	The HTTP request parameters. This is a name-value pair, such as REQ_PARAMS: [name : test].
API_NAME	The name of the API.
API_VER	The version of the API.
RES_PATHSPEC	The resource path spec associated with the API. For example, [RES_PATHSPEC: /collections/{collection}].
SVC_NAME	The name of the OMCe service consumed by the API. For example, [SVC_NAME: storage].
SVC_TYPE	The OMCe service type.
SVC_VER	The version of the OMCe service consumed by the API.
SVC_PARAM	The service parameters of the OMCe service consumed by the API.
REQ_HEADERS	The HTTP request headers. For example, [Authorization-Token : FixItFast-Technician/1.0],[Host : localhost:7001].
M_DEVICE_ID	The mobile device ID, which correlates the REST API requests sent to OMCe with the physical device that makes the request. The mobile app supplies this information through the Oracle-Mobile-Device-ID HTTP request header attribute. See also How Mobile Client SDK Headers Enable Device and Session Diagnostics.
M_DSID	The mobile diagnostic session ID. This attribute maps an app session on a specific device. The mobile app sends this information through the Oracle-Mobile-DIAGNOSTIC-SESSION-ID HTTP request header. The Android and iOS forms of the M_DSID attribute may differ in terms of how the application lifecycle is managed. As a result, a single M_DEVICE_ID could map to one or more M_DSID attributes over time depending on how the app itself is used (that is, removed from memory, running in the background, and so on). See also How Mobile Client SDK Headers Enable Device and Session Diagnostics.
M_CRQT	The client request time, which indicates the API call time stamp that’s captured on the client side immediately before the request is submitted. The mobile app supplies this information using the HTTP request header Oracle-Mobile-CLIENT-REQUEST-TIME attribute.
START_TIME	The start of request time stamp.
RESP_CODE	The HTTP response code of the API call.
RESP_STATUS	The HTTP response code, such as 200(OK).
RESP_HEADERS	The HTTP response headers.
RESP_ERROR	Any error or exception that occurs during the API call.
REQ_TIME	The total time (in milliseconds) that the OMCe server spent processing the request. This includes dispatching time and service time.
SVC_TIME	The total time (in milliseconds) that the OMCe service spent in processing the request. This excludes any routing or dispatching time. This attribute reflects only the time spent within the service.
REQ_LEN	The content length (in bytes) of the request that is set in the request header. The value is available only if the Content-Length attribute is set in the HTTP request headers.
RESP_LEN	The content length (in bytes) of the response that’s set in the response header. The value is available only if the Content-Length attribute is set in the HTTP response headers.
PATH_INFO	The servlet request path.
REQ_PARAMS	The HTTP request parameters.
ERROR	The OMCe error message ID, which is supplied by the OMCe request dispatcher to indicate why the request can’t be dispatched.
Message Text	A brief message.

Connector Message Details

Each connector message contains a brief description of the issue along with a set of connector-specific attributes:

[2015-02-04T03:40:42.961-08:00] [mobenv11_server_1] [NOTIFICATION] [MOBILE-38595] 
[oracle.cloud.mobile.ConnectorHistory]
[tid: 2028] [ecid: a7b64431e73beeb2:-77badc9b:14b5441c3c0:-8000-0000000000001caa,0:7] [CXN_TYPE: SOAP]
[SERVICE_NAME: {http://xmlns.oracle.com/mcs/test}OrderProcessorService] [SERVICE_PORT:
{http://xmlns.oracle.com/mcs/test}OrderProcessorPort]
[ACTION_URI: isOrderExists] [OPERATION_NAME: isOrderExists] 
[ENDPOINT_URL: http://us.example.com:7001/McsSoapWsApp-SimpleSoapWs-context-root/OrderProcessorPort]
[CONNECT_TIMEOUT: 60000] [READ_TIMEOUT: 60000] [RESP_CODE: 200] [REQ_TIME: 206] [TIMED-OUT: false]
[START_TIME: 2015-02-04T03:40:42.755-08:00] [MB_NAME: FiF_Customer]
[MB_VER: 1.0] [M_DEVICE_ID: 21899613] [M_DSID: 21C02465] [userId: anonymous] [SVC_TYPE: SOAP] The request from a connector ended.

The connector attributes include:

Attribute	Description	Example
TARGET	The name of the server where the connector resides.	mobenv11_server_1
Message ID	The message or the corresponding event types.	MOBILE-38595
Module ID	The ID of the Oracle Fusion Middleware component that logs the message.	oracle.cloud.mobile.ConnectorHistory
Thread ID	The identification of the Java thread in which the connector outbound request is made.	10
ECID	The execution context in which the outbound request from the connector has been made.	6ded6be4a583ed..00068
RID	The Relation ID of the execution context. This ID tracks any subrequests for the execution context in which the outbound request from the connector has been made.	0:1
MB_NAME	The name of the mobile backend.	FiF_Customer
MB_VER	The version of the mobile backend.	1.0
M_DEVICE_ID	The mobile device ID, which correlates the REST API requests sent to OMCe with the physical device that makes the request. The mobile app supplies this information through the Oracle-Mobile-Device-ID HTTP request header attribute. See also How Client SDK Headers Enable Device and Session Diagnostics.	21899613
M_DSID	The mobile diagnostic session ID. This attribute maps an app session on a specific device. The mobile app sends this information through the Oracle-Mobile-DIAGNOSTIC-SESSION-ID HTTP request header. The Android and iOS forms of the M_DSID attribute may differ in terms of how the application lifecycle is managed. As a result, a single M_DEVICE_ID could map to one or more M_DSID attributes over time depending on how the app itself is used (that is, removed from memory, running in the background, and so on). See also How Client SDK Headers Enable Device and Session Diagnostics.	21C02465

Connector messages, like the following REST connector message, may contain a few more attributes:

[2016-05-12T07:17:51.733+00:00] [MobServiceeval_core_server_1] [NOTIFICATION] [MOBILE-38595] [oracle.cloud.mobile.ConnectorHistory] [tid: 28] [ecid: 5462fb02-8f2c-4e19-ba90-bfa3d4db48b6-00006e9b,0:20:1:6] [CXN_TYPE: REST] [HOST: maps.googleapis.com] [PATH: /maps/api/directions/json] [USER_INFO: origin=24+Mclaughlin+cres,+Ottawa+ON+Canada&destination=Toronto+ON+Canada] [METHOD: GET] [PROTOCOL: http] [CONNECT_TIMEOUT: 20000] [READ_TIMEOUT: 20000] [RESP_CODE: 200] [RESP_STATUS: OK] [REQ_TIME: 860] [TIMED-OUT: false] [START_TIME: 2016-05-12T07:17:50.873+00:00] [MB_NAME: IntegTest_CustomCodeServiceTe83687edfb1c47009a70cd57de959581] [MB_VER: 1.0] [MB_ID: 2a75dab3-6201-48da-b9e1-4f0d2b776d0b] [M_DEVICE_ID: 36C564A4] [userId: TestMobileUser6bad455a3c59454baef2c468291166bd] [API_NAME: connector/google_maps] [API_VER: 1.0] [SVC_TYPE: REST] The request from a connector ended. 

Attribute	Description	Used in SOAP Connector Messages?	Used in REST Connector Messages?	Example
API_NAME	The name of the API.	Yes	Yes	connector/SOAPApi, connector/google_maps
API_VER	The version of the API.	Yes	Yes	1.0
CXN_TYPE	The connection type of outbound request.	Yes	Yes	SOAP
START_TIME	The time stamp marking the beginning of the outbound request.	Yes	Yes	2014–07–014T12:12:31.173–07:00
RESP_CODE	The HTTP status code of the connector’s outbound request.	Yes	Yes	200
RESP_STATUS	The response status message sent by the endpoint of the connector request.	Yes	Yes	OK
ERROR	Any errors (or exceptions) that occur during the connector outbound request.	Yes	Yes	SOAPFaultException, MOBILE-38595
REQ_TIME	The total time (in milliseconds) that the connector spent making the outbound request.	Yes	No	971
RESP_LEN	The content length (in bytes) of the response that is set in the response header. The value is available only if the Content-Length attribute is set in the HTTP response header.	Yes	No	196
HOST	The host name.	Yes	No	xyz.us.example.com
SVC_NAME	The connector service type.	Yes	Yes	REST, SOAP, ICS_REST, ICS_SOAP and FA
PORT	The port number.	Yes	No	9022
PROTOCOL	The transport protocol.	No	Yes	PROTOCL:https
PATH	The URI path information.	Yes	No	/wspath
QUERY	The query string.	Yes	No	query
USER_INFO	The user information URI.	Yes	No	sensor=false&origin=Ottawa&destination=Toronto
SERVICE_NAME	The name of the SOAP service.	Yes	No	http://myhost.us.example.com:7002/mobilesvc/IncidentService
SERVICE_PORT	The name of the SOAP service port.	Yes	No	http://mobilesvc/}IncidentServicePort
ACTION_URI	The SOAP action URI.	Yes	No	http://example.com/RightNow/GetIncidentById
OPERATION_NAME	The SOAP operation name.	Yes	No	GetIncidentById
ENDPONT_URL	The endpoint URL of the SOAP request.	Yes	No	http://us.example.com:/7001/mobilesvc/IncidentService
CONNECT_TIMEOUT	The SOAP connection timeout.	Yes	No	10000
READ_TIMEOUT	The SOAP read timeout (in milliseconds).	Yes	No	10000
Message Text	A brief message.	Yes	Yes	End of Connector Request
Timed-out	A Boolean value that when true, indicates that a timeout has occurred. Otherwise, the value is false.	Yes	Yes	TIMED-OUT:false

Configuring the Logging Level for Custom Code

To set the logging level, click Server Settings in the upper-right side of the page and then select the desired log level.

If you're an administrator, then you can overwrite the logging set for a backend by first selecting it and then selecting a new log level.

Diagnosing Custom Code

As an app developer who's debugging backend code, or as an administrator investigating a sudden increase of 5xx status codes, you can use correlated logging to identify flaws in code or changes in backend services that adversely affect the user experience.

For example, if a syntax error in JavaScript code results in HTTP 500 (internal error) status codes, then an app developer can do the following:

1. Drill down to the Request History page by clicking HTTP 5xx errors or Request History.

2. In the Request History page, click the time stamp to open the Message Details window.

3. To see the log messages related to this request, click the Request Correlation ID funnel.

4. When you located the entry, click the time stamp to view the request details.

   Tip:

   Adjust the logging level if you don't see any messages.

5. Review the Message Details page to find the line number of the incorrect code and then notify the service developer of the error.

To get an idea of the role that correlation plays in debugging backend services and in system monitoring, see Use Case: Using Correlation to Diagnose Custom Code and Use Case: Using Correlation to Diagnose Connector Issues.

Use Case: Using Correlation to Diagnose Custom Code

Developers for apps and backend services can use the backend-level diagnostics logs to pinpoint errors in the server-side JavaScript code. In this scenario, an app developer opens a backend called FiF_Customer and notices that the Diagnostics page shows that the environment has progressed to an adverse (amber) state because of an HTTP 5xx error.

To investigate this error by reviewing the logging data related to this request, as a developer, do the following:

1. Click HTTP 5xx Errors to open the Request History page.

2. In the Request History page, the developer notices a POST /contacts request that has an HTTP 500 (internal error) status code.

   
   
   
   
   

3. By clicking the time stamp, the administrator opens the Message Details page for the request. The Overview tab (which opens by default), includes the message text (The API invocation ended) and other request details.

   
   

   
   Description of the illustration message_details_2.png

   
   

4. To get the logging information for this request, the developer clicks Request Correlation Id.

   The log viewer includes an entry for a custom code problem, which is ranked as SEVERE.

5. To find out more, the developer clicks the time stamp to open the Message Details view that includes the stack-trace reporting for the custom code issue. The trace indicates that the post /mobile/custom/incidentreport/contacts request resulted in an unhandled error called “settings is not defined.”

   
   
   
   Description of the illustration diagnostics_custom_code_generated_msg.png
   
   

   Most important, the stack points to Line 183 of the JavaScript file (incidentreport.js) as the source for the unhandled error.

   
   

   
   Description of the illustration js_line_pinpoint.png

   
   

   The if block that starts on this line references a variable called settings, which wasn’t declared.

   
   Description of the illustration line_183.png

6. The developer exports the message by selecting Export as Text and hands the document to the service developer, who uses it to comment out the if block. The service developer then refreshes the implementation (.impl) file for the custom code API with the updated incidentreport.js file. Soon thereafter, the calls return an HTTP 200 (OK) status code.

   Tip:

   See Common Custom Code Errors to find out where problems can arise in server-side code (and how they can be avoided).

Use Case: Using Correlation to Diagnose Connector Issues

Like app developers, administrators also use correlation. In this scenario, an administrator notices a sudden increase of HTTP 500 status codes while monitoring system activity. The health status for the environment has changed to adverse (red).

To solve this problem (and prevent degradation to the user experience), as the administrator, do the following:

1. Click HTTP 5xx Errors on the Diagnostics page to open the Request History page.

   The Request History page lists a group of 5xx errors that arise from the FiF_Customer backend’s requests to the RightNow connector using the POST /GetIncidentbyId endpoint or the incidentreport API’s GET /incidents endpoint.
   
   Description of the illustration request_history_environment_external.png
   

2. Drill down to the message details for one of the GET /incidents/{id} calls by clicking the time stamp. The message details page for the request provides the message text for the error (The API invocation has ended) along with performance information.

   
   

   
   Description of the illustration get_message_details.png

   
   

3. To find out more, the administrator clicks the Request Correlation Id to view the logging data.

   Because the APIs are correlated to the connector calls, the Logs page shows SEVERE messages for both the incidentreport API and the RightNow Connector.

4. Open the Message Detail page for the RightNow connector by clicking the time stamp.

   The message details page identifies the error as a problem with the SOAP service (per error message MOBILE 16006) and provides the service name (incidentService) and port (7002) along with a tip: Check the validity of the SOAP connector configuration.

   
   

   
   Description of the illustration right_now_message_details.png

   
   
5. Confer with the RightNow service provider. After finding out that the service’s port number is now 7001, the administrator updates the RightNow connectors Endpoint with the correct port number.

   
   

   
   Description of the illustration change_connector_port.png

   
   

6. Test the GET /Incidents/{id} endpoint for the incidentreport API.

   After seeing the 200 (OK) response, the administrator confirms that the connector configuration is now correct.

   
   

   
   Description of the illustration right_now_200.png