Percepio Detect
Version 2025.2 (Oct 15, 2025)

This is the main entrypoint for the Percepio Detect documentation.

It is recommended to start by running the included demo. 
Instructions are found in the Demo Guides:

    "Percepio Detect Demo Guide - Linux.pdf"
    "Percepio Detect Demo Guide - Windows.pdf"

This document provides an overview of the solution and describes the overall process
for how to integrate Percepio Detect to monitor your own system. 

More detailed documentation for each part is found in
 - readme-client.txt
 - readme-server.txt
 - readme-receiver.txt


Solution overview:

The Percepio Detect solution consists of four parts, with the following relations and data flow:

Percepio DFM library (on device) --> Percepio Receiver --> Percepio Server --> Percepio Client

- Percepio DFM
  The main target-side component of Percepio Detect. This outputs "alerts" on faults and
  anomalies, including debugging data from other supporting libraries. In the demo, the data
  is written to the serial debug console in real time but DFM can be customized to output the
  data using any interface and/or store them on the device.
	
- Detect Receiver
  Reads the device output, extracts the DFM data, converts it to the
  expected format and saves it as alert files for the Detect Server.
	
- Detect Server
  Reads alert files from Receiver and presents a summary in the web browser (the "Dashboard").
  Provides easy access to debugging data provided in the alerts, such as traces and core dumps.
	
- Percepio Client
  An integrated set of developer tools for debugging alerts, including Tracealyzer and tools
  for viewing core dumps. Runs on each user’s computer to make it easy to debug reported issues.


Data Storage:

All data is stored locally and is controlled by the customer.

The main data storage is the "alert directory", containing the alert files from the device.
For a multi-user setup, this is typically a shared folder on a file server or similar.

The Server also contains a database, that stores configuration and metadata, including the
relative paths to the alert files. This is generated from the alert files.


Typical Setups:

- Single-user setup: The Server, Client and Receiver runs on the same computer. Demo data is
  already provided in the test-data directory.

- The Server runs on a shared server. Each user runs the Client on
  their local development computer. The Receiver can run on any computer with
  access to the device output, for example a test computer with CI test runners.

To monitor multiple devices, you can have multiple Receivers running on the same computer
(one per device/connection). If needed, you can also run the Receiver on multiple lab computers,
each monitoring one or multiple devices.


Getting Started:

Start with the Demo guide matching your host operating system. This describes how to Detect
with the default single-user setup to view the bundled demo data.
    
    "Percepio Detect Demo Guide - Linux.pdf"
    "Percepio Detect Demo Guide - Windows.pdf"

To make a full setup including device integration, follow the steps below. 

Note that these steps are not strictly sequential and can often be performed in 
parallel by different team members to get started faster. The Server, Client and
Receiver can also be tested in isolation using the provided example data in the
"test-data" folder, as described below.

Target-side:

T1. Integrate the DFM library, CrashCatcher and TraceRecorder to your project
    as described in "device-integration/Percepio Detect - Device Integration Guide.pdf"

    Also see the demo projects in device-integration/demo-projects. This is a snapshot
    of Percepio's Demos repository found at https://github.com/percepio/demos. 
   
    There is also a brief document about Tracealyzer for Bare Metal systems in
    "device-integration/Tracealyzer Bare Metal Intro.pdf" with pointers to more
    detailed documentation.

T2. Instrument all relevant error handlers in your code to report errors as DFM alerts.
    Note that processor fault exceptions are captured automatically, assuming that the
    Device Integration Guide has been followed.

T3. Use the TaskMonitor and Stopwatch features to monitor timing and CPU load metrics.
    This can provide traces in case of freezing, glitches, overloads and timing violations.
    Start by deciding what tasks to monitor with the TaskMonitor, and what code spans
    to monitor with stopwatches. Then add the corresponding DFM calls to measure high/low
    watermarks across representative tests and establish a baseline. Finally, set suitable
    warning levels when alerts should be generated (providing traces for analysis).

T4. Make test cases with DFM-generated alerts to ensure that the full Percepio Detect
    solution works as intended. For example, by causing a hard fault exception
    or by calling the DFM_TRAP macro.

Host-side:

H1. Set up the Server as described in percepio-server/readme-server.txt. 
    When running the server on a separate computer, make sure to set the BACKEND_IP variable
    in the Server start script. It should provide the IP address of the server.
    Notify your team members when it is ready and provide the server address.

H2. Set up the Client on a developer computer, as described in readme-client.txt.
 
H3. Set up the Percepio Receiver to provide the data transfer from device(s) to the server.
    See percepio-receiver/readme-receiver.txt for instructions.

H4. Finally, run your test cases (from T3) to verify that your alerts show up in the dashboard.
    Click on payloads to verify that you can view them in the Client.
   
    Finally, provide the Client and Receiver to your team, along with the Server address and port.


Verifying the setup using Test Data:

You will find test data for the Server, Client and Receiver in the test-data directory.
This allows for verifying the setup of each part individually.

- Verifying the Receiver setup: 
  Running the script without arguments uses the default input log file (the demo alerts) and
  writes them to the default alert directory, that is displayed by the Detect Server dashboard.
  As one set of demo alert files are already bundled in the Detect package, the Count column values
  should double for rows (Issues) originating from the bundled demo data.

  If using custom parameters for the Receiver, verify that you have a set of new directories
  with alert data in the output folder. There should be subdirectories following the structure
  DevAlert/<DeviceID>/<SessionID>/<AlertID>, each containing several files.

- Verifying the Server setup:
  Run the demo according to the Percepio Detect Demo Guide. This loads the provided alert files found
  in the test-data/alert-files directory. Open the server dashboard in the web browser and select the "Alerts" page.
  Click on Details for each alert. The Alert Key corresponds to a subdirectory of test-data/alert-files.
  Verify that all alerts in test-data/alert-files appear in the Alerts page listing.

- Verifying the Client setup:
  Run the demo according to the Percepio Detect Demo Guide. 

  Click one a core dump payload ("cc_coredump.dmp"). This should open a separate terminal window that shows the
  function call stack of the core dump, registers and other information.

  Click on a trace payload ("dfm_trace.psfs"). Percepio Tracealyzer should start and show the recorded trace.
  At the end of the trace, there is typically a "user event" (yellow label) showing "ALERT: <message>".
  
Notes:

* The solution is intended to run in a private, isolated network that is only available
  to trusted personell. There is no user management or authentication, so it must not
  be exposed to the public internet. It can be deployed in a private cloud environment
  assuming proper isolation from unauthorized access. Deployment in public cloud
  environments require a reverse proxy or similar to provide authentication.
  
* By default, the server uses HTTP communication when accessing it at port 8080.
  Encrypted HTTPS communication is also supported by accessing the server at port 8081.
  This requires a certificate in the percepio-server/cert folder. 
  A self-signed cerificate is included as example, but this will give a warning in the
  web browser since not a CA-signed certificate.

* On Linux hosts, when using the Tracealyzer tool bundled in the Client, it can't show
  the User Manual or web links as there is no web browser in the Docker container.
  You can instead access the User Manual at http://localhost:8085/tz-user-manual/,
  assuming the Client is running and the Tracealyzer license has been installed.
   
For questions and assistance, please contact Percepio at 
 
     https://percepio.com/contact-us/

Copyright (c), Percepio AB, 2025
https://percepio.com

    
