Added overview and local setup instructions to README

README.md

@@ -2,32 +2,46 @@
 
 An overview of the application, its purpose, and potential use cases
 
+TC Weather API is a simple wrapper around the OpenWeatherMap 2.5 current weather API that adds in OpenTelemetry for observability.
+
+Potential use cases include:
+
+- Get the current weather anywhere in the world using only a city name
+  - Additionally limit by state (US-only) and country
+- Use popular tracing platforms like [Jaeger](https://www.jaegertracing.io/) to analyze collected trace data about this app and the weather API it uses
+- Use as a template / proof of concept for your own Rails-based OpenTelemetry projects that may have nothing to do with the weather: dream big, but measure the dream! :)
+
 ## Prerequisites
 
 - Ruby version: 3.3.0
+- Docker (for running Jaeger locally)
 
 ## Configuration
 
-- Sign up for an OpenWeatherMap API KEY
+- Clone this repository
+- Make sure you have the necessary Ruby version installed (see Prerequisites above)
+- Run `bundle install` in the project root
+- Sign up for an [OpenWeatherMap API KEY](https://home.openweathermap.org/api_keys)
 - Copy `.env.template` to `.env` and set `OPEN_WEATHER_MAP_API_KEY` to the value of your new API KEY
 
 ## Running the app locally
 
-TODO: A simple guide on how to set up and run the application locally
-
 ### Without telemetry
 
-Good old-fashioned `rails s`
+Start the local server with `rails s` in the project root and navigate to http://localhost:3000/forecasts/Tokyo as an example. Change the city as needed.
 
 ### With telemetry, sent to console
 
 You can run the app locally with telemetry output sent to console like so:
 
 `env OTEL_TRACES_EXPORTER=console OTEL_METRICS_EXPORTER=console rails server -p 8080`
 
+- Navigate to http://localhost:8080/forecasts/Tokyo
+- Look at the console window where you started the server to view telemetry output
+
 ### With telemetry data exported to a local Jaeger container
 
-Alternatively, if you would like to explore your traces in a UI, you can quickly run a Docker container of Jaeger like so (prerequisites: Docker):
+Alternatively, if you would like to explore your traces in a UI (highly recommended), you can quickly run a Docker container of Jaeger like so (prerequisites: Docker):
 
 ```shell
 docker run -d --name jaeger \
@@ -46,20 +60,16 @@ docker run -d --name jaeger \
   jaegertracing/all-in-one:latest
 ```
 
-Start the app: `env OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" rails server -p 8080`
-
-Then navigate to http://localhost:16686/.
+- Start the app server with this command: `env OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" rails server -p 8080`
+- Navigate to http://localhost:8080/forecasts/Tokyo
+- Experiment with a few more API requests with different cities
+- Navigate to http://localhost:16686/ and use the Jaeger UI to explore your traces
 
 Learn more about exporters at https://opentelemetry.io/docs/languages/ruby/exporters/
 
-### Signoz
+### Important note about Jaeger and Metrics
 
-```shell
-OTEL_EXPORTER=otlp \
-OTEL_SERVICE_NAME=tc-weather-api \
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
-rails server
-```
+This application records traces and metrics, but Jaeger UI only supports tracing. Currently the app sends metrics output to the console even with the above Jaeger instructions. Look at your console output to see metrics output, which is currently sent every 60 seconds.
 
 ## API docs
 

config/routes.rb

@@ -4,7 +4,7 @@
 
   # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
   # Can be used by load balancers and uptime monitors to verify that the app is live.
-  get "up" => "rails/health#show", as: :rails_health_check
+  get 'up' => 'rails/health#show', :as => :rails_health_check
 
   # Defines the root path route ("/")
   # root "posts#index"