Essential Troubleshooting Tools in OutSystems 11

Introduction

In this blog post, we’ll explore the essential troubleshooting tools available in OutSystems 11. These tools empower developers and IT professionals to quickly diagnose issues, streamline problem-solving processes, and optimize application performance. Whether it’s analyzing logs, debugging code, or ensuring your environment is healthy, OutSystems 11 provides everything you need to keep your applications running smoothly.

---

1. Service Center

The Service Center in OutSystems is an essential tool for managing, monitoring, and troubleshooting applications across your environment. Here, we’ll explore its primary features, show you how to access it, and detail key troubleshooting functionalities that help ensure your applications run smoothly.

Overview of Service Center Features

The Service Center serves as the control hub for all OutSystems applications and infrastructure. Its functionalities are essential for developers, system administrators, and IT teams alike:

• Performance Tracking: Monitor CPU, memory usage, database access, and screen load times to pinpoint performance bottlenecks.
• Error Logging: Access detailed logs for application and system errors, including stack traces, user session details, and error contexts.
• Access Control: Manage roles and permissions, controlling which users and teams can access specific applications or features.
• Integration Monitoring: Track API calls, external integrations, and scheduled tasks to ensure seamless connectivity with external systems.
• Analytics and Reports: Access analytics on application usage, user activity, and module performance, which can be vital for debugging and optimization.

How to Access and Navigate the Service Center

To access Service Center:

1. Open your OutSystems environment URL: In a browser, navigate to your OutSystems environment, typically at https://.outsystemscloud.com/ServiceCenter.
2. Log in with your OutSystems credentials. Only users with administrator privileges can fully access the Service Center features.
3. Explore the Dashboard: Once logged in, you’ll see an intuitive dashboard with easy-to-navigate sections for monitoring, logging, user management, integrations, and application settings.

Key Troubleshooting Capabilities

Service Center provides several key capabilities for troubleshooting issues:

1. Application Performance Monitoring

• Go to Monitoring > Analytics > Screen Analytics to view metrics like screen load times, response times, and user interactions. This helps you identify screens or actions that may be causing performance slowdowns.

2. Error Logs

• Access Monitoring > Errors to see a list of all application errors. Each log entry includes a timestamp, error message, and stack trace.
• Use this information to trace errors to specific parts of your application. For instance, if an API call fails due to incorrect data, the error log will often indicate the exact source of the problem.

3. Timers and Scheduled Tasks

• Go to Monitoring > Timers to view and control scheduled tasks in your applications. You can run, stop, or troubleshoot timers that handle background processes.
• Each timer displays details like the last execution time, execution duration, and error logs if any issues occurred.

4. Integrations Monitoring

• For applications that rely on external integrations (APIs, databases), go to Monitoring > Integrations.
• Here, you’ll find logs on API calls, response times, status codes, and errors.
• This is essential for diagnosing issues like failed API requests or connection problems, helping you identify root causes and take corrective action.

Example Code for Logging Custom Messages

OutSystems also allows you to log custom messages in Service Center using the Log Message action, which can help with debugging specific parts of your application.

Here’s an example:

// Inside your logic flow, use the Log Message action to log a custom message
LogMessage(
    Message: "User entered order details.",
    LogLevel: Info,
    Module: "OrderManagement"
);

This custom message will now appear in Monitoring > General Log, making it easier to follow the flow of execution and troubleshoot specific events in your application logic.

---

2. Performance Monitor

The Performance Monitor in OutSystems is a powerful tool for understanding application resource usage and identifying bottlenecks. It provides developers with detailed insights into CPU and memory usage, database access times, and more. Here’s a guide on how to set it up, use it, and interpret its data to optimize your OutSystems applications.

Introduction to Performance Monitor

The Performance Monitor captures real-time performance data for your applications, tracking critical metrics like:

• CPU Usage: Helps you see if specific actions or screens are overloading the CPU, which could slow down application performance.
• Memory Usage: Identifies memory-hogging processes that could lead to application crashes or slower responses.
• Database Query Times: Tracks the duration of database queries and identifies inefficient or slow-running queries.
• API Call Latency: Measures the response times for external APIs, helping to pinpoint integrations that may be causing delays.

Setting Up and Using Performance Monitor

To enable and use the Performance Monitor:

1. Access the Service Center: Log in to your OutSystems Service Center by navigating to https://.outsystemscloud.com/ServiceCenter.
2. Go to the Monitoring Section: Once logged in, navigate to Monitoring > Analytics > Performance Monitor.
3. Configure Performance Monitoring: Here, you can select the specific data points to monitor. For example, you might choose to monitor CPU and memory usage on specific applications or modules that have known performance issues.

Once configured, Performance Monitor will start capturing data, which you can then review to identify performance bottlenecks.

Interpreting Performance Data

The data captured by the Performance Monitor is broken down into several components. Here’s how you can interpret this data to optimize your application:

1. Screen Load Times

• Navigate to Analytics > Screen Performance to review load times for each screen in your application.
• Look for screens with high load times, as they may be affected by inefficient queries, heavy UI components, or large data loads.

2. Database Queries and Aggregates

• Use Analytics > Database Performance to view the execution time for queries and aggregates.
• Look for queries that take longer than expected to complete, as they might be causing delays.

Example query optimization:

Suppose you have a slow-running query that retrieves orders with multiple joins. You can optimize it by indexing frequently filtered columns or simplifying the query structure.

-- Before optimization
SELECT Orders.*, Customers.Name
FROM Orders
INNER JOIN Customers ON Orders.CustomerID = Customers.CustomerID
WHERE Orders.OrderDate BETWEEN '2023-01-01' AND '2023-01-31';

-- After optimization (e.g., adding indexes)
CREATE INDEX idx_OrderDate ON Orders (OrderDate);
SELECT Orders.*, Customers.Name
FROM Orders
INNER JOIN Customers ON Orders.CustomerID = Customers.CustomerID
WHERE Orders.OrderDate BETWEEN '2023-01-01' AND '2023-01-31';

3. CPU and Memory Usage

• Check Analytics > System Performance for CPU and memory usage metrics.
• Excessive CPU usage often points to resource-intensive actions, loops, or complex calculations.
• High memory usage can indicate memory leaks, such as when large datasets are loaded unnecessarily.

Example troubleshooting steps for high CPU/memory usage:

• Optimize data fetching: Avoid loading large datasets at once. Use pagination to fetch only necessary records.
• Refactor loops: Minimize nested or redundant loops that increase processing time.

Example code snippet in Service Studio:

// Before optimization: Large dataset loaded at once
FetchAllRecords();

// After optimization: Paginate to fetch only 10 records at a time
FetchRecordsWithPagination(StartIndex: 0, Limit: 10);

4. API Call Latency

• If your application relies on third-party APIs, use Integration Monitoring to track response times and error rates for each call.
• For high-latency API calls, consider caching data if it’s not highly dynamic, or setting up retries with exponential backoff.

Example: Caching data for frequently used, slow APIs.

// Pseudocode for caching API data
IF CacheIsEmpty THEN
    SET Cache = CallExternalAPI();
END;
RETURN Cache;

---

3. Environment Health Check

The Environment Health Check in OutSystems is a powerful diagnostic tool that scans your environment to ensure optimal performance and stability. By running regular health checks, you can identify and resolve potential issues before they impact your applications. Here’s a guide to setting up a health check, interpreting the results, and addressing common issues that may arise.

Running an Environment Health Check

To run an Environment Health Check:

1. Open Service Center: Log in to your OutSystems environment’s Service Center at https://.outsystemscloud.com/ServiceCenter.
2. Go to the Health Check Section: In the Service Center dashboard, navigate to Monitoring > Environment Health.
3. Initiate the Scan: Click on Run Health Check to start a scan of your environment.
4. View the Report: Once the scan is complete, a detailed report will be generated, outlining the status of various elements within your environment.

Understanding the Results

The Health Check report covers multiple aspects of your environment, such as:

• Server Status: This section shows the health of each server in your OutSystems environment, checking for issues like high CPU or memory usage.
• Database Connectivity: Tests your database connections to ensure queries run efficiently and data is retrieved without delays.
• Application Health: Monitors deployed applications for any inconsistencies, outdated modules, or dependency issues that could impact stability.

Example output:

Health Check Report Summary:

1. **Server Status**:
   - Server: "Production Server 1"
   - Status: Healthy
   - CPU Usage: 55%
   - Memory Usage: 68%

2. **Database Connectivity**:
   - Database: "OutSystemsDB"
   - Status: Warning - High latency detected on some queries.

3. **Application Health**:
   - Application: "OrderManagement"
   - Issue: Module dependency outdated (Warning)
   - Recommended Action: Update dependency to the latest version.

Common Issues and Their Resolutions

Here’s a look at some common issues the Health Check may flag, along with recommended solutions:

1. Database Latency

• Issue: High latency in database queries may be flagged if certain queries or modules are taking too long to execute.
• Solution:
  • Review the slow-running queries and optimize them (e.g., add indexes, simplify queries).
  • Use Service Studio to refactor queries in your aggregates or SQL actions.

Example SQL optimization:

-- Before optimization
SELECT * FROM Orders WHERE OrderDate >= '2023-01-01';

-- After optimization (adding index on OrderDate)
CREATE INDEX idx_OrderDate ON Orders (OrderDate);
SELECT * FROM Orders WHERE OrderDate >= '2023-01-01';

2. Server Resource Exhaustion

• Issue: High CPU or memory usage on one or more servers.
• Solution:
  • Review the Health Check report for applications with high resource usage.
  • Consider scaling your environment (e.g., adding more server resources or instances).
  • Optimize specific screens or actions within applications that may be causing the load.

3. Outdated Dependencies

• Issue: Applications with outdated dependencies, such as modules or components not updated to the latest versions.
• Solution:
  • Open Service Studio, go to the Dependencies tab, and update outdated dependencies.
  • Test the application to ensure that updating dependencies does not introduce breaking changes.

---

4. Log Analyzer

The Log Analyzer in OutSystems Development Cloud is an essential tool for troubleshooting by providing insights into runtime errors, user activity, and system events. Logs can be filtered and reviewed to help developers identify patterns and root causes, making it easier to resolve issues quickly and efficiently.

Accessing and Using the Log Analyzer

To access the Log Analyzer:

1. Open Service Center: Navigate to your Service Center at https://.outsystemscloud.com/ServiceCenter.
2. Go to the Monitoring Section: Once logged in, navigate to Monitoring > General Log or Error Log.
3. Filter Logs: Use the filtering options to refine the logs by criteria such as application, module, user, or error type. This helps you focus on specific issues within a particular application or module.

Interpreting Log Data

Log entries provide valuable details about application events, errors, and warnings. Here’s how to interpret some common log data points:

1. Error Messages and Stack Traces: When an error occurs, logs capture the error message, a stack trace, and often contextual data (e.g., user actions leading to the error).
   • Example: If an API call fails, the log entry might show an “HTTP 500” error with details on the endpoint and parameters used. The stack trace will pinpoint where the call failed in the code.
2. Warnings and Informational Messages: Warnings indicate potential issues that might not immediately cause failures but should be monitored.
   • Example: You might see warnings about long-running queries or high memory usage. While these may not immediately impact performance, they are indicators to review for optimization.
3. Session Information: Logs often capture session data, including user information, which can be useful to reproduce or trace specific user issues.
   • Example: An error log may include user session ID, username, and actions taken. This data helps identify if the issue is user-specific or impacts all users.

Example log entry interpretation:

Timestamp: 2024-11-01 12:30:00
Application: OrderManagement
Severity: Error
Message: "Null Reference Exception"
Stack Trace:
  - Module: OrderManagement
  - Action: ProcessOrder
  - Line: 45
User: TuyenTran
Session: abc123
Description: An error occurred while processing the order due to missing data in the order details.

In this example, you can identify that the error occurred in the ProcessOrder action of the OrderManagement application. The issue might be due to missing data in the order, which can be validated to prevent future errors.

Best Practices for Log Analysis

Using the Log Analyzer effectively requires consistent monitoring and following some best practices:

1. Regularly Review Logs: Schedule time to review logs for potential warnings and errors, even if they are not causing immediate issues. This proactive approach can help you catch problems early.
   • Example: Set up a weekly review of the General and Error Logs to spot trends, such as recurring warnings or errors.
2. Set Up Alerts for Critical Errors: Configure alerts for severe errors (like application crashes) so you’re immediately notified when they happen.
   • Example: Use the OutSystems monitoring feature or integrate with external tools like Azure Monitor to receive alerts when a critical error log entry is detected.
3. Focus on Recurring Issues: Pay special attention to recurring errors or warnings, as they often indicate underlying problems that need addressing.
   • Example: If an API call consistently fails with a specific error code, investigate the root cause rather than treating it as an isolated incident.
4. Use Custom Log Messages for Debugging: Add custom log messages in your code to capture specific events or data, which can be helpful during development and debugging.

Example of custom logging in OutSystems:

// Inside your logic flow, use the Log Message action to log a custom event
LogMessage(
    Message: "Order processing started for Order ID: " + OrderId,
    LogLevel: Info,
    Module: "OrderManagement"
);

This log entry will appear in the General Log and helps you trace the flow of specific actions, like order processing, making it easier to debug related issues.

---

5. Integration Studio

OutSystems Integration Studio is a powerful tool for developing, managing, and troubleshooting integrations with external systems. It allows developers to bring custom code, connect to APIs, and manage integrations, making it essential for applications that require external data sources or services. Here’s a detailed guide on using Integration Studio for managing and debugging integrations.

Overview of Integration Studio

Integration Studio enables OutSystems developers to:

• Create and manage extensions with custom code in languages like .NET or Java.
• Integrate with external systems, such as databases, REST APIs, and SOAP services.
• Debug integration components to troubleshoot issues in real-time.

You can access Integration Studio by downloading it from your OutSystems account. Once installed, open Integration Studio and connect it to your OutSystems environment.

Debugging Integration Components

Integration Studio offers debugging tools for testing integration flows. Here’s how you can troubleshoot common integration issues:

1. Test API Calls: Use Integration Studio’s Test feature to simulate requests to external APIs. This is useful for checking connectivity, validating responses, and ensuring data is passed correctly.
2. Debugging Steps:
   • Set Breakpoints: In Integration Studio, place breakpoints within your custom code or API logic to pause execution and inspect variable values.
   • Step Through Code: Use step-by-step execution to check the flow of data and identify where issues might occur.
   • View Error Messages: Integration Studio provides detailed error messages for each failed call, helping you pinpoint specific issues.

Example Code for Debugging a REST API Call:

If you’re integrating with a REST API for retrieving customer data, here’s how you might set up and debug an API call in Integration Studio:

// Define the API call and set up error handling
RESTRequest request = new RESTRequest();
request.Endpoint = "https://api.example.com/customer";
request.Method = "GET";

// Add a breakpoint here to inspect the request object before sending
RESTResponse response = request.Send();

// Check the response status
if (response.StatusCode != 200) {
    LogMessage("Error: " + response.ErrorMessage);
} else {
    // Process the response data
    var customerData = response.Data;
}

Common Integration Issues and Solutions

1. Connectivity Failures

   • Issue: The API server may be unreachable, or a network configuration issue could be blocking access.
   • Solution: Check the API endpoint URL, ensure correct port access, and test connectivity from your environment. You can also simulate the request in Integration Studio to identify where it fails.

   Error Example: "Could not connect to API: Connection refused at https://api.example.com."
   Solution: Verify the endpoint and network configurations in Integration Studio.
   

2. Authentication Errors

   • Issue: Many APIs require specific authentication methods (e.g., API keys, OAuth tokens), which must be correctly configured in Integration Studio.
   • Solution: Verify that your authentication credentials are correct and up-to-date. Use the Test feature in Integration Studio to check authentication before deploying.

   Example of setting a Bearer token:

   RESTRequest request = new RESTRequest();
   request.Endpoint = "https://api.example.com/customer";
   request.Method = "GET";
   request.Headers.Add("Authorization", "Bearer " + authToken);
   

3. Data Mismatch Errors

   • Issue: Data mismatches occur when the external API schema does not align with your OutSystems application’s data model, causing issues with parsing or processing responses.
   • Solution: Ensure data structures in OutSystems match the external API’s response format. Use Integration Studio’s Transformations feature to map and align data fields.

   Example transformation:

   // Transforming the JSON response into a compatible format
   if (response.Data["customer_name"] != null) {
       var customerName = response.Data["customer_name"].ToString();
   } else {
       LogMessage("Data Mismatch: Expected 'customer_name' field not found.");
   }
   

---

6. Debugger

The OutSystems Debugger in Service Studio is an essential tool for identifying and resolving code-level issues in your applications. It enables developers to inspect and trace application logic at runtime, providing real-time insights into how data flows and how variables change during execution. Using breakpoints, watch expressions, and advanced debugging features, you can troubleshoot even the most complex problems in your OutSystems applications.

Setting Up the Debugger

To begin using the OutSystems Debugger:

1. Open Your Application in Service Studio: Launch Service Studio and open the application you want to debug.
2. Start a Debugging Session: Click the Debugger tab in the top-right corner of Service Studio, and click Start Debugging. This will start a debugging session and allow you to execute the application step-by-step while tracking variable values.
3. Run the Application in Debug Mode: Once you’ve started the debugger, run the application as you normally would. However, it will now run in debug mode, allowing you to pause execution at breakpoints.

Using Breakpoints and Watch Expressions

1. Setting Breakpoints: A breakpoint is a marker you set in the application logic, where execution will pause. This allows you to inspect the current state of variables and expressions at that point in the logic flow.

   To set a breakpoint:

   • In Service Studio, open the logic flow (e.g., an action or screen) where you want to set the breakpoint.
   • Click on the line number where you want to pause execution. A red dot will appear, indicating the breakpoint.

   Example:

   • In an action that processes an order, set a breakpoint before the order validation step. This lets you inspect the order data to verify if the correct data is being passed through.

   Action: ProcessOrder
   - Set breakpoint before "ValidateOrder" logic
   

2. Using Watch Expressions: Watch expressions allow you to track the value of specific variables or expressions while debugging. You can add these expressions to watch critical variables and ensure that their values change as expected during execution.

   To add a watch expression:

   • During a debug session, open the Watch Expressions window.
   • Add the variable or expression you want to track (e.g., a customer’s order total).

   Example:

   Watch Expression: OrderTotal
   Watch the value of `OrderTotal` during the processing to ensure it's being calculated correctly.
   

3. Inspecting Variables and Expressions: While the debugger is paused at a breakpoint, you can hover over variables in your logic flow to see their current values. You can also expand complex objects (like lists or structures) to inspect their properties.

Advanced Debugging Techniques

1. Step Through Code Line by Line: Once the debugger hits a breakpoint, you can step through the code line by line. This is useful when you want to understand exactly how your application is processing each instruction.

   • Step Over: Executes the current line of code and moves to the next line, skipping over any functions called on that line.
   • Step Into: Executes the current line of code and steps into any functions or subroutines, allowing you to inspect them more closely.
   • Step Out: If you’re inside a function, it will complete the function execution and return to the previous step in the code.

   Example:

   Step into the "ValidateOrder" function to ensure the order validation logic is working as expected.
   

2. Skip Over Loops or Conditional Blocks: The Debugger allows you to skip over loops or conditionals, which is helpful when you’re trying to isolate specific code issues or focus on a particular part of your application logic.

   • If you’re debugging a loop that iterates over customer orders, and you want to skip a specific iteration to observe the behavior at a later point, you can use the Step Over feature to bypass iterations.

   Example:

   If you have a loop processing multiple items in an order, skip over each item’s iteration to focus on a specific one where the error occurs
   

3. Monitor Variable Values: The Debugger allows you to track how variables change during execution. You can monitor values such as customer names, order totals, or status flags to ensure they hold the correct data.

   For instance, while debugging an order processing flow, you can check if the OrderStatus variable is updated correctly after each step:

   OrderStatus: Pending -> Processed -> Shipped
   

4. Examine Call Stack: If an error occurs during execution, the Call Stack view lets you trace the sequence of function calls that led to the issue. This is particularly useful for identifying errors that happen deep within nested functions or subroutines.

   Example:

   Call Stack: View the series of function calls that led to the failure of the "ProcessPayment" action.
   

5. Logging and Debug Output: In addition to using breakpoints and watch expressions, you can use Log Message actions to output messages during debugging. This is useful for tracing how data flows through your application, especially in more complex scenarios.

   Example of adding log messages:

   LogMessage("Processing order with ID: " + OrderId, LogLevel: Info);
   

---

Conclusion

OutSystems 11 offers a robust suite of troubleshooting tools to help developers and IT teams keep applications running smoothly. From the all-encompassing Service Center to the performance-enhancing Profiler, these tools provide deep insights into every layer of your applications, ensuring they operate at peak efficiency. Leveraging these tools can help streamline your problem-solving processes, enhance performance, and provide users with a seamless experience.

---

Additional Resources

To dive deeper into these tools, check out the following resources:

• OutSystems Documentation
• OutSystems Community Forum
• OutSystems Learning Paths

Explore these links for more in-depth tutorials, best practices, and community support as you work to keep your OutSystems applications running smoothly.