Faro Demo

This small project demonstrates how to use the Faro and its packages.

The app is built using:

• Client
  • React
  • React Router
  • Redux
  • Redux Toolkit
  • Redux Toolkit Query
  • Faro
  • Server-side rendering (SSR)
  • React Bootstrap
  • React Hook Form
• Server
  • Express
  • PostgreSQL
  • Sequelize
  • OpenTelemetry
    • Instrumentations:
      • Express
      • HTTP
      • PostgreSQL
      • Winston
  • Winston
  • prom-client
• Misc
  • dotenv
  • Vite

Besides the app itself, the demo can also spawn the entire architecture for testing Faro:

• Grafana
• Loki
• Tempo
• Mimir

Installation

The demo can be run using containers. This is the easiest way to get started as it will spin up all the necessary services. Moreover, the source code is mapped in the container so everytime a change occurs, there's no need to restart the container(s).

The app will be available at http://localhost:5173 and Grafana will start at http://localhost:3000/.

To start everything up, simply run:

docker compose --profile demo up -d

This will automatically install dependencies, build the demo and start it in development mode.

Instrumentation

There is various data that is captured in this app. Some data is captured manually while other data is automatically captured by the instrumentation provided by either Faro and/or OpenTelemetry.

You can have a look over the following pages to understand what and how data is collected.

• Errors
• Events
• Logs
• Measurements
• Metas
• Traces

User Journey

The next section will present the steps that a user usually does when navigating through the app and what useful data is collected from those actions. In some cases the mechanism behind it is also explained. To find out how to visualize the data, you can refer the one of the docs from the Presentation chapter.

All the actions will be performed assuming that the demo is freshly ran and the database is empty.

1. Navigate to the Homepage
   • Web Vitals are captured. They can be observed in the Frontend dashboard in Grafana
   • Traces for the document load are created. They can be found in the Explore page in Grafana using the Trace ID property at the top of the page
   • An error is registered because the endpoint that returns the state of the user returns 401 status code
   • The Session ID at the top can be used to filter out the data collected during the current user journey
   • 
2. Navigate to the Seed page
   • route_change event is registered with the new URL and the React route associated to that specific URL
   • 
3. Click on the Seed button to add some default data in the database
   • The following events are registered:
     • seed
     • Sending Request - created with every fetch request
     • Request Completed - created with every successful fetch request
   • The following spans are created:
     • The button click
     • A manual span which is associated with the seed event
     • The HTTP request to the API
     • The database calls
   • The Trace ID that appears under the button can be used to see the traces mentioned above
   • 
4. Click on the Seed button again to generate an error:
   • The following events are registered:
     • seed
     • Sending Request - created with every fetch request
     • Request Failed - created with every failed fetch request
   • The traces are different from the step above because the DB threw an exception
   • The Trace ID that appears under the button can be used to see the traces mentioned above
   • 
5. Navigate to the Register page
   • route_change event is registered with the new URL and the React route associated to that specific URL
6. Enter [email protected] as email and the fill in the rest of the fields then click on the Register button
   • The following events are registered:
     • registerAttempt
     • registerFailed
   • Traces are collected as well
   • 
7. Navigate to the Login page
   • route_change event is registered with the new URL and the React route associated to that specific URL
8. Login with the following credentials: [email protected] as email and test as password
   • route_change event is registered with the new URL and the React route associated to that specific URL
   • The following events are registered:
     • loginAttempt
     • loginSuccess - The registerAttempt -> registerFailed -> loginAttempt -> loginSuccess sequence allows us to understand that a user tried to create an account, already having one
   • Traces are collected as well
   • All the data captured from this point until logout will be associated with the John Doe user. Associating the John Doe user and session ID will allow us to see what actions the user performed prior logging in.
9. Click on the First Article
   • route_change event is registered with the new URL and the React route associated to that specific URL
     • what's different from the other route_change events is that the route for this event is not identical to the URL but what React received as an input (/articles/view/:id)
10. Input some text in the Add Comment section and click Create Comment
    • The following events are registered:
      • createArticleCommentAttempt
      • createArticleCommentSuccessfully
11. Click on the Logout button in the header