Updated documentation

splunk · Oct 10, 2023 · c8c3551 · c8c3551
1 parent f15ed94
commit c8c3551
Show file tree

Hide file tree

Showing 14 changed files with 132 additions and 117 deletions.
diff --git a/docs/assets/screenshots/f1_2023_telemetry_settings.png b/docs/assets/screenshots/f1_2023_telemetry_settings.png
diff --git a/docs/event_guide/event_support.md b/docs/event_guide/event_support.md
diff --git a/docs/f1_2023/configuration.md b/docs/f1_2023/configuration.md
@@ -0,0 +1,34 @@
+# Configuration
+
+## Number of Rigs
+
+Usually this will be 1, but in some cases at large events multiple rigs will be used. In this case you can specify the number of rigs here.
+
+## Observability Cloud
+
+### Realm
+
+Realm name for the Observability Cloud realm you want to send data to e.g. `us1`, `eu0` etc.
+
+### Access Token
+
+Observability Cloud access token (must have `ingest` capability).
+
+## Splunk Cloud/Enterprise
+
+### HEC URL
+
+HEC URL for Splunk Cloud/Enterprise e.g. `https://simulator.prod.splunkcloud.com:8088`.
+
+### HEC Token
+
+HEC Token for Splunk Cloud/Enterprise.
+
+## Enable sending metrics
+
+You are able to send the metrics to both Observability Cloud and Splunk Cloud/Enterprise. To enable either or both just tick the relevant boxes.
+
+* Tick **Enable Observability Cloud** to enable sending data to O11y Cloud.
+* Tick **Enable Splunk Cloud** to enable sending data to Splunk Cloud.
+
+Finally click **Save Configuration**
diff --git a/docs/f1_2023/game.md b/docs/f1_2023/game.md
@@ -0,0 +1,18 @@
+# F1 2023 Telemetry Configuration
+
+In the F1 2023 you will need to configure the telemetry settings to send data to the F1 2023 container.
+
+On the main screen select **Game Options**, then click on **Settings** and then **Telemetry Settings**.
+
+Here you will need to set the following:
+
+* UDP Telemetry: **On**
+* UDP Broadcast Mode: **Off**
+* UDP IP Address: **IP address of the laptop/EC2 instance running the container**
+* UDP Port: **20777**
+* UDP Send Rate: **10Hz**
+* UDP Format: **2023**
+
+If you are running multiple simulators, you will need to repeat the above for each remebering to change the UDP Port for each simulator.
+
+![F1 2023 Telemetry Settings](/assets/screenshots/f1_2023_telemetry_settings.png)
diff --git a/docs/f1_2023/ingest.md b/docs/f1_2023/ingest.md
diff --git a/docs/f1_2023/listener.md b/docs/f1_2023/listener.md
@@ -4,8 +4,6 @@ The UDP listener(s) can be started from the web interface. Under the Data Driver
 
 Once the listeners are running the you will see **UP** in each rig box.
 
-
-
 In the web interface click on the `Administration` menu (top right), this will give you a drop down menu where you can easily start and stop the listeners. The web interace will visually show when the listeners are up or down.
 
 ![Listener Up](/assets/screenshots/f1_2023_listeners_running.png)
diff --git a/docs/f1_2023/observability.md b/docs/f1_2023/observability.md
@@ -0,0 +1,5 @@
+# Splunk Observability Cloud
+
+In order to send metrics to Splunk Observability Cloud you will need access to an Organization. A free trial is available [here](https://www.splunk.com/en_us/download/o11y-cloud-free-trial.html). Ensure you select the same region as the one you are using for the F1 Simulator.
+
+Once you are successfully logged into Splunk Observability Cloud, you will need to obtain an Access Token with the `ingest` capability. This can be done by following the instructions [here](https://docs.splunk.com/Observability/admin/authentication-tokens/org-tokens.html#ingest-tokens).
diff --git a/docs/f1_2023/pre-reqs.md b/docs/f1_2023/pre-reqs.md
@@ -0,0 +1,37 @@
+# Pre-requisites
+
+## Recommended environment(s)
+
+- Apple MacBook (Apple Silicon M1/M2)
+- AWS/EC2 (Ubuntu 22.04 or above)
+    - t2.large (2 vCPU, 8GB RAM)
+    - External IP address
+    - Inbound access on ports `8501/tcp` and `20777-20784/udp`
+
+## Install Docker
+
+Docker is required to run the F1 2023 UDP listener and UI. The UDP listener will take the UDP stream from F1 2023 and transform the stream into metric payload for Splunk Observability Cloud and Splunk Enterprise/Cloud. The UI is used to configure where to send the metrics, start/stop the UDP listener(s) and change the name of the current driver.
+
+The following instructions will install Docker on your laptop or EC2 instance:
+
+=== "Mac OS"
+
+    [Download Docker Desktop for Mac with Apple Silicon](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64)
+
+=== "Ubuntu"
+
+    ```bash
+    sudo apt remove docker docker-engine docker.io containerd runc
+    sudo apt update
+    sudo apt install ca-certificates curl gnupg -y
+    sudo install -m 0755 -d /etc/apt/keyrings
+    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+    sudo chmod a+r /etc/apt/keyrings/docker.gpg
+    echo \
+    "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
+    "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
+    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+    sudo apt update
+    sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
+    sudo usermod -aG docker $USER
+    ```
diff --git a/docs/f1_2023/requirements.md b/docs/f1_2023/requirements.md
diff --git a/docs/f1_2023/setup.md b/docs/f1_2023/setup.md
@@ -1,59 +1,32 @@
-# Mac OS Initial setup
+# Running the F1 2023 container
 
-Open iTerm2 and change into your **Documents** directory
+For both Mac OS and Ubuntu the following Docker command will run the F1 2023 container:
 
 ```bash
-cd ~/Documents
+docker run --name f1_2023 -d -p 8501:8501/tcp -p 20777:20777/udp rcastley895/f1_2023
 ```
 
-## Clone the Data Driver GitHub repository
+The above will run the F1 2023 container in the background and expose port `8501` for the UI and port `20777` for the UDP listener.
 
-Inside this directory clone the Data Driver GitHub repository.
+!!! note
 
-```git
-git clone https://github.com/splunk/datadrivers
-```
-
-!!! info
-    If the above `git` command can not be found you will have to install Xcode Command Line tools for Mac OS. This can be done by running the following:
+    If you are using more than one simulator you can expose up to 8 UDP ports, for example, if you have 4 simulators running you would start the container by running:
 
     ```bash
-    xcode-select –install
+    docker run --name f1_2023 -d -p 8501:8501/tcp -p 20777:20777/udp -p 20778:20778/udp -p 20779:20779/udp -p 20780:20780/udp rcastley895/f1_2023
     ```
 
-Next, change into the `f1_2023` directory:
-
-```bash
-cd datadrivers/f1-2023
-```
-
-## Create Python Virtual Environment
+To validate the container is running correctly you can run the following command:
 
-We now need to create a virtual Python environment and install the required Python modules:
-
-```bash
-python3 -m venv venv
-. venv/bin/activate
-pip3 install -r requirements.txt --upgrade
-```
-
-!!! info
-    If you are using a Mac with an M1 chip you will need to install the following Python modules:
+=== "Command"
 
     ```bash
-    pip3 install --upgrade --force --no-dependencies --no-cache-dir --no-binary :all: --compile numpy
-    pip3 install --upgrade --force --no-dependencies --no-cache-dir --no-binary :all: --compile pandas
+    docker port f1_2023
     ```
 
-    You can then install the remaining Python modules:
+=== "Output"
 
     ```bash
-    pip3 install -r requirements.txt --upgrade
+    8501/tcp -> 0.0.0.0:8501
+    20777/udp -> 0.0.0.0:20777
     ```
-
-## Start the Streamlit Web UI
-
-```bash
-```bash
-streamlit run stream.py
-```
diff --git a/docs/f1_2023/splunk.md b/docs/f1_2023/splunk.md
@@ -0,0 +1,3 @@
+# Splunk Cloud/Enterprise
+
+In order to send metrics to Splunk Cloud/Enterprise you will need access to an HEC Token.
diff --git a/docs/f1_2023/ui.md b/docs/f1_2023/ui.md
@@ -0,0 +1,7 @@
+# F1 2023 Web Interface
+
+To access the UI open a browser and navigate to `http://<ip_address>:8501` where `<ip_address>` is the IP address of the laptop/EC2 instance running the container.
+
+Here you can configure where the game data is going to be sent.
+
+![Listener Down](/assets/screenshots/f1_2023_web_ui_settings.png)
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,4 @@
 ---
 template: home.html
-title: Splunk - Data Drivers
+title: Home
 ---
-
-Welcome to Data Drivers!
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,5 +1,5 @@
-site_name: Data Drivers
-repo_name: splunk/datadrivers
+site_name: Splunk Data Drivers - F1 Simulator
+repo_name: splunk/f1-simulator
 repo_url: https://github.com/splunk/f1-simualtor
 edit_uri: edit/main/docs
 theme:
@@ -30,18 +30,23 @@ markdown_extensions:
 
 nav:
   - Home: index.md
+  - F1 2023:
 #  - Event Guide:
-#    - Introduction: event_guide/index.md
+#    - Overview: event_guide/index.md
 #    - Event Support: event_guide/event_support.md
 #    - Pre-Work: event_guide/prework.md
 #    - Game Configuration (Solo): event_guide/solo.md
 #    - Game Configuration (LAN): event_guide/lan.md
 #    - Host Laptop: event_guide/host_laptop.md
-  - F1 2023 Simulator:
-    - Requirements: f1_2023/requirements.md
-    - Initial Setup: f1_2023/setup.md
-    - Ingest Settings: f1_2023/ingest.md
-    - Starting UDP Listener(s): f1_2023/listener.md
+
+    - Pre-requisites: f1_2023/pre-reqs.md
+    - Setup: f1_2023/setup.md
+    - Accessing the Web Interface: f1_2023/ui.md
+    - Configuration: f1_2023/configuration.md
+    - Game Configuration: f1_2023/game.md
+#    - Splunk Observability Cloud: f1_2023/observability.md
+#    - Splunk Enterprise/Cloud: f1_2023/splunk.md
+
 
 extra:
   social:
@@ -56,10 +61,9 @@ extra:
     - icon: fontawesome/brands/youtube
       link: https://www.youtube.com/user/splunkvideos
 
-
   generator: false
 
 extra_css:
   - stylesheets/custom.css
 
-copyright: Copyright &copy; 2022 - Splunk Inc.
+copyright: Copyright &copy; 2023 - Splunk Inc.