Reviewing periodic task logs via the Grafana web interface

You can access and analyze logs of periodic tasks (such as subscription charging, invoice calculation, taxation, periodic payments, and report generation) via the Grafana web interface. Grafana displays the periodic task logs (taskstack.log/task_queue.log files) collected from all servers and stored in OpenSearch.

• Logging in
• Default dashboard
• Filtering log records
  • By viewer execution ID
  • By time range
  • By log level
  • By label values
  • By message text
• Viewing log details
• Downloading logs
• Sharing a dashboard view
• Specifics

To open the Grafana web interface:

1. Open the Configuration server web interface at https://<your-portaswitch-host>:8700.
2. On the login page, enter your credentials and click Log in.
3. On the main page, click the dropdown in the top-right corner and select BillingAdmin Logs UI.

   

This opens the Grafana web interface in a new browser tab.

After logging in, Grafana opens the default dashboard for periodic task logs.

It consists of two areas:

• Number of logs per [interval] – a chart showing log volume over time, broken down by level (Debug/Info, Warn, Error). Useful for spotting spikes in errors or warnings at a glance.
• Logs Viewer – list of log entries. Each row represents one log entry and can be expanded to show full details.

Above both areas, a filter bar provides the following controls:

• Number of logs per – controls how logs are grouped on the chart. For example, setting it to “1h” means the chart shows the total number of logs for each one-hour period.
• Viewer limit – the maximum number of log rows loaded into the Logs Viewer at a time.
• Viewer level – a dropdown for selecting which log levels to show in the Logs Viewer. By default, all levels are shown: info, debug, warn, and error.
• Viewer message filter – used to search log entries by message text. Supports plain text and regular expressions. See Filtering logs by message text for more details.
• Viewer execution ID – used to search log entries by a specific task execution ID. Paste an ID to instantly see all log entries related to that exact periodic task run, without setting any other filters. See Filtering logs by execution ID for more details.
• Chart/viewer filters – used to search log entries by attributes such as scope, environment, tags, or custom attributes. See Filtering logs by label values for more details.
• Time range selector – controls the time period displayed across the chart and Log Viewer. See Filtering logs by time range for more details.
• Refresh – click to manually reload the dashboard, or use the dropdown to set an automatic refresh interval (from every 5 seconds up to once a day).

The quickest way to find logs for a specific periodic task run is to use the Viewer execution ID filter. This eliminates the need to combine multiple filters such as customer ID, timestamps, and task type.

For broader searches, the other filters can be used individually or combined.

Every periodic task run (a single execution of a periodic task, such as a specific subscription charging) gets a unique execution ID in PortaBilling. Subtasks within a parent task (e.g., charge_subscriptions/calc_charge_fee and charge_subscriptions/apply_charge_fee) get their own IDs too.

All related IDs appear together as a linked chain: parent task/subtask 1/subtask 2 /…/subtask N. By filtering logs with any ID from the chain, you can choose the level of detail you need (from a single operation to the entire periodic task run).

Execution IDs can be taken from the xDR details in the PortaBilling web interface.

To investigate a specific periodic task:

1. In PortaBilling, open the xDR for a specific periodic task (e.g., subscription charge) and copy its execution ID.

   

   The Execution ID column is not displayed in the xDR list by default. To enable it, click Settings in the xDR list toolbar > Customize columns > and select Execution ID.

   

2. In Grafana, paste this ID into the Viewer execution ID field.

   

3. The Logs Viewer shows the log entries for that task.

To broaden the scope, expand any log entry and copy a higher-level ID from the execution chain. Paste it into the same Viewer execution ID field to view logs for the parent task.

If needed, combine the execution ID filter with other filters.

To filter logs by the time range:

1. Click the time range dropdown in the top-right corner.

   

2. Select a preset range such as Last 1 hour, Last 1 day, or Last 7 days. Alternatively, click Absolute time range and enter custom From and To values. Click Apply time range to reload the dashboard.

Use the Viewer level dropdown to select which log levels to show. Select or clear info, debug, warn, and error as needed.

Use Chart/viewer filters to search logs by their attributes.

To add a filter:

1. Click the Chart/viewer filters field – a dropdown appears showing all available attributes. Start typing to narrow the list. Select an attribute.

   

2. Select an operator: = (equals), != (not equal), =~ (matches regex), !~ (does not match regex), or < (less than).

   

3. Select or type in the value.

   

Repeat the steps to add more filters – all active filters are applied together to narrow the results. To remove a filter, click the Close × next to it.

The following attributes are available:

Use the Viewer message filter to search logs by message text. Your input is automatically wrapped with the wildcard pattern .*, so plain text matches messages containing that text anywhere in the log text. For example, typing discount applied matches any message containing that phrase.

The search is case-sensitive. The following operators are supported:

• | – OR operator. For example, discount|refund matches messages containing either "discount" or "refund"
• [ ] – matches any one character in the specified set or range. For example, error [45][0-9][0-9] matches error codes starting with 4 or 5
• ( ) – groups part of the expression. For example, charge(back)? matches both "charge" and "chargeback"
• { } – specifies how many times the preceding pattern can repeat. For example, [0-9]{3} matches exactly three digits, while [a-z]{2,5} matches between two and five lowercase letters
• . – matches any single character
• ?, +, * – repeat the preceding character zero-or-one, one-or-more, or zero-or-more times, respectively

For the full syntax reference, see the Elasticsearch regexp syntax documentation.

To see the full content of a log record:

1. Click on any row in the log table.
2. The log details panel expands and shows fields such as environment, task type, log level, and any additional attributes.

   It also includes exec_ids – the full chain of execution IDs for this task, shown as parent task / subtask 1 / subtask 2 / … / subtask N.

   

3. To collapse the panel, click the row again.

To download log records for offline review or sharing with support:

1. Apply the filters and time range to display the records you need.
2. Click ⋮ Menu in the top-right corner of the Logs Viewer area, hover over Inspect, and select Data.

   

   

3. Optionally, expand the Data options to adjust the export:
   • Apply panel transformations – when enabled, the downloaded CSV reflects any transformations (e.g., merges, filters, calculations) configured under  ⋮ Menu > Edit > Transformations.
   • Formatted data – when enabled, the formatting from the Field/Override tabs (e.g., decimals) is applied.
   • Download for Excel – adds a special header to the CSV so Excel opens it correctly without encoding issues.
4. Click Download CSV.

   

To share the current dashboard state (including active filters and time range) with a colleague:

1. Click Share in the top-right corner of the dashboard to copy the link.

   

2. Send the URL to the recipient who has access to Grafana. When they open it, Grafana will restore the same time range and filter settings.

• The number of log rows loaded into the Logs Viewer at one time is controlled by the Viewer limit setting. If you are not seeing the expected entries, check that the limit is not set too low.
• After a periodic task writes a log entry, it may take up to 5 minutes for that entry to appear in Grafana. This delay occurs because logs are first indexed into OpenSearch before they become available for querying; in most cases the indexing completes within 1–2 minutes.
• Log retention in OpenSearch is limited. Contact the PortaOne Support team to verify the retention policy for your installation.