|
| 1 | +# Monitoring |
| 2 | + |
| 3 | +## Frontend monitoring |
| 4 | +This section suggests an approach for using Elastic's Real User Monitoring (RUM) in order to capture user interactions with our client-side application CoMPAS-OpenSCD. The following instructions assume you/your organization already count on a hosted Elasticsearch Service deployment or an Elastic Cloud organization account with Kibana as the frontend of your monitoring stack and a URL to access it. Also it is assumed that you deploy `compas-open-scd` by using Kubernetes (and [the compas-open-scd docker public docker image](https://hub.docker.com/r/lfenergy/compas-open-scd) or your own generated image). |
| 5 | + |
| 6 | +### 1. Getting your serverUrl |
| 7 | +Navigate to your Kibana URL and select the space that you would like to associate with your frontend app (default if you don't have several spaces in Kibana). Then open the drawer menu and navigate to `APM`: |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +In the top right corner of this page click on `Add data`: |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +Then scroll down to APM Agents and select `RUM (JS)`: |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +There are two suggested code blocks for setting up the RUM Agent, find in any of them the `serverUrl` param and copy/paste it somewhere in your notes, we will use this URL later in a posterior step. |
| 20 | + |
| 21 | +*Note: You have two options for getting your init script, you either install the `@elastic/apm-rum` dependency in your project or you set up the agent with `<script>` tags. In this document we will describe an approach for the latter.* |
| 22 | + |
| 23 | +### 2. Using the /public/init-js script |
| 24 | + |
| 25 | +The __compas-open-scd__ project features a reference to an "empty" javascript resource at `index.html` (line:42) |
| 26 | +```html |
| 27 | + <script src="./public/init-js/init.js"></script> |
| 28 | +``` |
| 29 | + |
| 30 | +This init javascript file has the purpose to allow for dynamic configuration of each compas-open-scd deployment. |
| 31 | + |
| 32 | +In a private repository create a copy of `init.js` (or edit if you already have your own copy of the file with custom init scripts) in a folder, let's call it `path-to-init-js` and add the following code: |
| 33 | + |
| 34 | +```js |
| 35 | +const script = document.createElement('script'); |
| 36 | +script.type = 'text/javascript'; |
| 37 | +// download and host your preffered RUM Agent version minified from https://github.com/elastic/apm-agent-rum-js/releases |
| 38 | +script.src = 'https://your-cdn-host.com/path/to/elastic-apm-rum.umd.min.js'; |
| 39 | +script.async = true; |
| 40 | +script.crossorigin = "anonymous"; // provides support for CORS |
| 41 | +script.onload = function () { |
| 42 | + elasticApm.init({ |
| 43 | + serviceName: 'compas-open-scd', // or preferred name, this will be used to filter out results in Kibana |
| 44 | + serverUrl: 'https://your-own-serverUrl.with.a.specific:port', // replace with serverUrl found in Step 1 |
| 45 | + environment: 'test', // The environment where the service being monitored is deployed, e.g. 'production', 'development', 'test', etc. Default: '' |
| 46 | + }); |
| 47 | +} |
| 48 | +document.querySelector('head').appendChild(script); |
| 49 | +``` |
| 50 | + |
| 51 | +### 3. Cloning private git repo using Kubernetes initContainers and Kubernetes Secrets |
| 52 | +Start by generating a personal acccess token in Github and make sure you authorize your token to access your private repo (configure SSO if needed), your token must have checked the write:packages scope checkbox. |
| 53 | + |
| 54 | +Then you must create your Kubernetes Secret: |
| 55 | +```sh |
| 56 | +kubectl create secret generic test-secret --from-literal=username='foo' --from-literal=password='ghp_12345yourgithubtoken' |
| 57 | +``` |
| 58 | + |
| 59 | +Modify your YAML deployment template to include an initContainers section: |
| 60 | +```yaml |
| 61 | + containers: |
| 62 | + (...) |
| 63 | + volumeMounts: |
| 64 | + - mountPath: /app/public/init-js |
| 65 | + name: "data-volume" |
| 66 | + subPath: init-js |
| 67 | + (...) |
| 68 | + initContainers: |
| 69 | + - name: "init-clone-repo" |
| 70 | + image: alpine/git |
| 71 | + imagePullPolicy: Always |
| 72 | + args: |
| 73 | + - clone |
| 74 | + - --single-branch |
| 75 | + - --branch |
| 76 | + - -- |
| 77 | + - 'https://$(GIT_USERNAME):$(GIT_PASSWORD)@gitlab.company.com>/path/to/repo.git' |
| 78 | + - '/path-to-init-js/' |
| 79 | + env: |
| 80 | + - name: GIT_USERNAME |
| 81 | + valueFrom: |
| 82 | + secretKeyRef: |
| 83 | + key: username |
| 84 | + name: test-secret |
| 85 | + - name: GIT_PASSWORD |
| 86 | + valueFrom: |
| 87 | + secretKeyRef: |
| 88 | + key: password |
| 89 | + name: test-secret |
| 90 | + volumeMounts: |
| 91 | + - mountPath: /path-to-init-js |
| 92 | + name: "data-volume" |
| 93 | + volumes: |
| 94 | + - name: "data-volume" |
| 95 | + emptyDir: {} |
| 96 | +``` |
| 97 | +
|
| 98 | +Now apply changes to deployment with the new persistent volume init: |
| 99 | +
|
| 100 | +```sh |
| 101 | +kubectl apply -f your-yaml-template.yaml |
| 102 | +``` |
| 103 | + |
| 104 | +Your pod should be up now with an initContainer that clones your private repo and copies the contents of `/path-to-init-js/` to compas-open-scd's `/app/public/init-js/`. |
| 105 | + |
| 106 | +### 4. Web server configuration |
| 107 | +// TODO: Asking Pascal to help me describe the problem with outgoing POST requests from Elastic RUM Agent in compas-open-scd and how to approach the solution for it. |
| 108 | + |
| 109 | +### 5. References |
| 110 | + |
| 111 | +[Full documentation about APM Real User Monitoring JavaScript Agent](https://www.elastic.co/guide/en/apm/agent/rum-js/5.x/intro.html) |
| 112 | + |
| 113 | +[Full APM Guide](https://www.elastic.co/guide/en/apm/guide/8.6/apm-quick-start.html) |
| 114 | + |
| 115 | +[@stefvnf's medium blog post about cloning git repos using Kubernetes initContainers and Secrets](https://stefvnf.medium.com/cloning-git-repos-using-kubernetes-initcontainers-and-secrets-8609e3b2d238) |
0 commit comments