Skip to content

Particular/ServicePulse

Repository files navigation

ServicePulse Current Version

ServicePulse provides real-time production monitoring for distributed applications. It keeps track of the health of a system's endpoints, monitors for processing errors, sends failed messages for reprocessing, and ensures the specific environment's needs are met, all in one consolidated dashboard.

ServicePulse is part of the Particular Service Platform, which includes NServiceBus and tools to build, monitor, and debug distributed systems.

See the ServicePulse documentation for more information.

Setting up the project for development

ServicePulse is in the process of migrating from AngularJS to Vue.js, during which both frameworks are used to serve parts of the application. In the development environment, AngularJS and Vue.js HTTP servers are run side-by-side behind a reverse proxy. This enables accessing both applications from the same domain, i.e., localhost:1331 where uri prefixed with /a/ are served by AngularJS, and Vue.js handles the rest. This mimics the production deployment where the Vue.js application is deployed in the main folder and AngularJS in the /a/ subfolder.

graph LR
  subgraph ServiceControl
    ScMonitoring
    ScError
  end

  subgraph ServicePulse
    AngularJs
    VueJs
  end

  Browser --> Nginx[Nginx<br>Reverse Proxy]
  Nginx -- http://host.docker.internal:5174/a/ --> AngularJs[AngularJS<br> Development Server]
  Nginx -- http://host.docker.internal:5173 --> VueJs[Vue.js<br> Development Server]

  AngularJs --> ScMonitoring[Monitoring Instance]
  AngularJs --> ScError[Main Instance]

  VueJs --> ScMonitoring
  VueJs --> ScError

Setting up ServiceControl Main and ServiceControl Monitoring instances

ServicePulse mainly presents data provided by ServiceControl and ServiceControl Monitoring instances.

The URLs for both services can be set in ServicePulse.Host/vue/public/app/js/app.constants.js under the scConfig constant.

Setting up package managers

ServicePulse uses npm and Bower as package managers. For the solution to work, dependencies must be downloaded before launching the ServicePulse website.

Install dependencies

Install the following dependencies if you don't have them installed yet

Set development environment

Tip

Using the ServicePulse\src\run-dev.cmd batch file will execute steps 1 - 3.

Step 0 - Using a suitable IDE for frontend development

Even though Visual Studio or Rider seem to be adequate IDEs for front-end development, they don't tend to do a good job with the latest front-end frameworks, linting, and formatting. Because of that, we have extra recommendations for you to be even more successful at front-end development.

Step 1 - run the Nginx reverse proxy

Open a command window and navigate to ServicePulse\src\ServicePulse.Host path (NOTE: On Windows, ensure cmd is being used and not PowerShell). Run nginx that will act as the reverse proxy for AngularJS and Vue.js applications:

docker run -it --rm -p 1331:1331 -v ./nginx.conf:/etc/nginx/nginx.conf:ro --name service-pulse-dev nginx

Step 2 - run the AngularJS development server

Navigate to ServicePulse\src\ServicePulse.Host\angular and:

  • run npm install to install all the npm dependencies
  • run the following command npm run dev. This will host a dev server on port 5174 and start watching for changes in /angular directory

Note

For compatibility with Node.js versions 17 and higher, it's essential to set the NODE_OPTIONS environment variable to --openssl-legacy-provider when loading and running the angularJS app. This configuration is specified in the .npmrc file located at the root of the Angular folder ServicePulse\src\ServicePulse.Host\angular. Any npm command executed from the Angular directory, including those in CI/Release workflows, will automatically have the necessary environment variable set.

Step 3 - run the Vue.js development server

Navigate to ServicePulse\src\ServicePulse.Host\vue and:

  • run npm install to install all the npm dependencies
  • run the following command npm run dev (this will host a dev server on port 5173 and start watching for changes in /vue directory)

If npm run dev fails with an error related to git submodules not being correctly configured, run the npm install command again to ensure all required dependencies are available, and then run npm run dev.

Step 4 - open the browser

After doing the above steps, navigate to http://localhost:1331 to see the ServicePulse application.

Provided npm scripts

Vue.js

  • dev - runs vite that starts development server doing hot reload over source files
  • build - runs build script that outputs files to ..\app folder
  • lint - checks with eslint all vue, ts and js files
  • type-check - runs TypeScript in no emit mode

AngularJS

  • test - runs js tests in ServicePulse.Host.Test project
  • setup - this command runs few commands
    • installs the npm packages
    • runs webpack
  • load - this command does the same thing that setup but webpack is run only once to produce artifacts. This command is used by the builder
  • serve - serves js artifacts using http-server
  • webpack - runs webpack command, which does the following things for the given modules (monitoring, configuration)
    • joins js together
    • runs babel transpiler
    • has a file watcher to run the above whenever file is saved
  • lint - checks with eslint all js files
  • dev - runs in parallel two scripts webpack and serve

NOTE: Webpack observes files and updates the artifacts whenever they are changed, however at the moment not every bit of code is processed by webpack. Only monitoring and configuration-related files are.

Configuring automated tests

For information on how to run automated tests, please follow ServicePulse.Host.Tests/Readme.

Running from ServicePulse.Host.exe

It is possible to run ServicePulse directly via ServicePulse.Host.exe.

Step 1 - reserve URL ACL

ServicePulse.Host.exe depends on a self-hosted web server. A URL ACL reservation needs to be set up to start the project. Either run Visual Studio with Administrative privileges or run the following command to add the required URL ACL reservation:

add urlacl url=URL

Where URL is the configured URL on the local machine.

Step 2 - build ServicePulse site

Execute the build script from the command line:

PowerShell -File .\build.ps1

NOTE: It might be necessary to change the PowerShell execution policy using Set-ExecutionPolicy Unrestricted -scope UserPolicy

Step 3 - run ServicePulse.Host.exe

Build and run the ServicePulse.Host project in the IDE.

Supported browser versions

ServicePulse is supported on the following desktop browser versions:

Docker image deployment

Dockerfiles for ServicePulse resides within the src folder. There are 2 docker files:

Building & staging docker images

The docker files are all built as part of the release workflow, pushed to the Docker hub, and tagged with the version of ServicePulse being deployed. More details are available in the documentation.

E.g., If we were deploying version 1.30.1 of ServicePulse, the build configurations after the Deploy step will build the following 2 containers for ServicePulse and tag them 1.30.1:

  • particular/servicepulse:1.30.1
  • particular/servicepule-windows:1.30.1

These images are tagged with the specific version of ServicePulse being built and pushed to the corresponding public particular/servicepulse{-os} repositories. At this point, the docker images are considered staged. This means that if someone is watching the feed directly, they can install the staged images by explicitly specifying the exact tag, e.g., docker pull particular/servicepulse:1.30.1.

Promoting docker images to production

When a ServicePulse release is promoted to production, one of the steps is to take the staged images and re-tag them as the following:

  • particular/servicepulse:1.30.1 => particular/servicepulse:1
    • This is so that customers who are only interested in updates within a major can install the specific major only and not worry about breaking changes between major versions being automatically rolled out. Useful for auto upgrading containers in a production environment.
  • particular/servicepulse:1.30.1 => particular/servicepulse:latest
    • Primarily for developers wanting to use the latest version (docker-compose up -d --build --force-recreate --renew-anon-volumes
    • This is only in the case where the release's major version is the same as the current latest major version.
      • If a fix is being backported to a previous major then the :latest tag will not be updated.
      • If a release targets the current latest major or is a new major after the previous latest then the :latest tag is updated to match the version being released.

Once the tagging has been completed, the images are considered to be publicly released.