diff --git a/.air.toml b/.air.toml
new file mode 100644
index 0000000..63a13bd
--- /dev/null
+++ b/.air.toml
@@ -0,0 +1,3 @@
+[build]
+cmd = "go build -o tmp/twelvedata-exporter"
+bin = "./tmp/twelvedata-exporter"
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index e69de29..6d6d7b7 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -0,0 +1,34 @@
+name: release
+
+on:
+ workflow_dispatch:
+
+jobs:
+ goreleaser:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Set up Go
+ uses: actions/setup-go@v5
+ with:
+ go-version: "1.22.3"
+
+ - name: Login to GitHub Container Registry
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Run GoReleaser
+ uses: goreleaser/goreleaser-action@v5
+ with:
+ distribution: goreleaser
+ version: latest
+ args: release --clean
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.golangci.yml b/.golangci.yml
index 72dd9fe..f3faffb 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -1,6 +1,7 @@
# Refer to https://golangci-lint.run/usage/configuration/
run:
+ go: "1.20"
concurrency: 4
timeout: 5m
skip-dirs:
diff --git a/.goreleaser.yml b/.goreleaser.yml
index e93e779..b0a43c7 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -10,10 +10,6 @@ github_urls:
# set to true if you use a self-signed certificate
skip_tls_verify: false
-before:
- hooks:
- - go mod tidy
-
builds:
- main: main.go
id: twelvedata-exporter
@@ -33,11 +29,15 @@ builds:
gcflags:
- all=-trimpath=.
+dockers:
+- id: twelvedata-exporter
+ image_templates:
+ - 'ghcr.io/umatare5/twelvedata-exporter:latest'
+ - 'ghcr.io/umatare5/twelvedata-exporter:{{ .Tag }}'
+ dockerfile: Dockerfile.goreleaser
+
archives:
- name_template: '{{ .ProjectName }}-v{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}'
- format_overrides:
- - goos: windows
- format: zip
release:
prerelease: auto
diff --git a/Dockerfile.goreleaser b/Dockerfile.goreleaser
new file mode 100644
index 0000000..4d8b372
--- /dev/null
+++ b/Dockerfile.goreleaser
@@ -0,0 +1,8 @@
+FROM alpine
+
+WORKDIR /app
+COPY twelvedata-exporter /bin/
+
+EXPOSE 9341
+USER ${UID}
+ENTRYPOINT [ "/bin/twelvedata-exporter" ]
diff --git a/LICENSE b/LICENSE
index f628684..2dfc689 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
MIT License
-Copyright (c) 2023 umatare5
+Copyright (c) 2024 umatare5
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index 54d6d98..03f8e17 100644
--- a/README.md
+++ b/README.md
@@ -2,92 +2,163 @@
-This is a simple stock and funds quotes exporter for
-[prometheus](http://prometheus.io). This exporter allows a prometheus instance
-to monitor prices of stocks, ETFs, and mutual funds, possibly alerting the user
-on any desirable condition (note: prometheus configuration not covered here.)
+twelvedata-exporter is a Prometheus Exporter to fetch quotes from Twelvedata API.
-## Data Provider Setup
+This exporter allows a prometheus instance to monitor prices of stocks, ETFs, and mutual funds.
-This project uses the [stonks page](https://stonks.scd31.com) to fetch stock
-price information. This method **does not** support Mutual Funds, but avoids
-the hassle of having to create an API key and quota issues of most financial
-API providers.
+> [!Important]
+>
+> To access the Twelvedata API, you need an access token. Please register with [Twelvedata](https://twelvedata.com/) in advance and generate an access token by referring to [the official document: Getting Started - Authentication](https://twelvedata.com/docs#authentication).
-The program is smart enough to "memoize" calls to the financial data provider
-and by default caches quotes for 10m. This should reduce the load on the
-finance servers, as prometheus tends to scrape exporters on short time
-intervals.
+## Installation
-## Building the exporter
+```bash
+docker run ghcr.io/umatare5/twelvedata-exporter
+```
-To build the exporter, you need a relatively recent version of the [Go
-compiler](http://golang.org). Download and install the Go compiler and type the
-following commands to download, compile, and install the twelvedata-exporter binary
-to `/usr/local/bin`:
+> [!Tip]
+> If you would like to use binaries, please download them from [release page](https://github.com/umatare5/twelvedata-exporter/releases).
+>
+> - `linux_amd64`, `linux_arm64`, `darwin_amd64`, `darwin_arm64` and `windows_amd64` are supported.
+
+## Syntax
```bash
-OLDGOPATH="$GOPATH"
-export GOPATH="/tmp/tempgo"
-go get -u -t -v github.com/umatare5/twelvedata-exporter
-sudo mv $GOPATH/bin/twelvedata-exporter /usr/local/bin
-export GOPATH=$OLDGOPATH
-rm -rf /tmp/tempgo
+NAME:
+ Fetch quotes from Twelvedata API - twelvedata-exporter
+
+USAGE:
+ twelvedata-exporter COMMAND [options...]
+
+VERSION:
+ 0.1.0
+
+COMMANDS:
+ help, h Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+ --web.listen-address value, -I value Set IP address (default: "0.0.0.0")
+ --web.listen-port value, -P value Set port number (default: 9341)
+ --web.scrape-path value, -p value Set the path to expose metrics (default: "/price")
+ --twelvedata.api-key value, -a value Set key to use twelvedata API [$TWELVEDATA_API_KEY]
+ --help, -h show help
+ --version, -v print the version
```
-## Docker image
+## Configuration
+
+This exporter supports following environment variables:
+
+| Environment Variable | Description |
+| :------------------- | ------------------------------------ |
+| `TWELVEDATA_API_KEY` | The API Key to be used for requests. |
+
+## Metrics
+
+This exporter returns following metrics:
+
+| Metric Name | Description | Type | Example Value |
+| --------------------------------- | ---------------------------------------- | ----- | --------------- |
+| `twelvedata_change_percent` | Changed percent since last close price. | Gauge | `1.00975` |
+| `twelvedata_change_price` | Changed price since last close price. | Gauge | `1.72` |
+| `twelvedata_price` | Real-time or the latest available price. | Gauge | `172.06` |
+| `twelvedata_previous_close_price` | Closing price of the previous day. | Gauge | `170.34` |
+| `twelvedata_volume` | Trading volume during the bar. | Gauge | `1.5206856e+07` |
+
+Click to show full metrics
+
+```plain
+# HELP twelvedata_change_percent Changed percent since last close price.
+# TYPE twelvedata_change_percent gauge
+twelvedata_change_percent{currency="USD",exchange="NASDAQ",name="Alphabet Inc",symbol="GOOGL"} 1.00975
+# HELP twelvedata_change_price Changed price since last close price.
+# TYPE twelvedata_change_price gauge
+twelvedata_change_price{currency="USD",exchange="NASDAQ",name="Alphabet Inc",symbol="GOOGL"} 1.72
+# HELP twelvedata_failed_queries_total Count of failed queries
+# TYPE twelvedata_failed_queries_total counter
+twelvedata_failed_queries_total 0
+# HELP twelvedata_previous_close_price Closing price of the previous day.
+# TYPE twelvedata_previous_close_price gauge
+twelvedata_previous_close_price{currency="USD",exchange="NASDAQ",name="Alphabet Inc",symbol="GOOGL"} 170.34
+# HELP twelvedata_price Real-time or the latest available price.
+# TYPE twelvedata_price gauge
+twelvedata_price{currency="USD",exchange="NASDAQ",name="Alphabet Inc",symbol="GOOGL"} 172.06
+# HELP twelvedata_queries_total Count of completed queries
+# TYPE twelvedata_queries_total counter
+twelvedata_queries_total 1
+# HELP twelvedata_query_duration_seconds Duration of queries to the upstream API
+# TYPE twelvedata_query_duration_seconds summary
+twelvedata_query_duration_seconds_sum 0
+twelvedata_query_duration_seconds_count 0
+# HELP twelvedata_volume Trading volume during the bar.
+# TYPE twelvedata_volume gauge
+twelvedata_volume{currency="USD",exchange="NASDAQ",name="Alphabet Inc",symbol="GOOGL"} 1.5206856e+07
+```
+
+
Prometheus Quotes Exporter
")
- fmt.Fprintf(w, "To fetch quotes, your URL must be formatted as:
")
- fmt.Fprintf(w, "http://localhost:%d/price?symbols=AAAA,BBBB,CCCC", s.Port)
- fmt.Fprintf(w, "Examples:
")
- fmt.Fprintf(w, "")
-
- symbols := []string{
- "AMD",
- "AMZN,GOOG",
- }
-
- for _, symbol := range symbols {
- fmt.Fprintf(w, "- ", s.Port, symbol)
- fmt.Fprintf(w, "http://localhost:%d/price?symbols=%s
", s.Port, symbol)
- }
-}
-
-// priceHandler handles the "/price" endpoint. It creates a new collector with
-// the URL and a new prometheus registry to use that collector.
-func (s *Server) priceHandler(w http.ResponseWriter, r *http.Request) {
- log.Printf("URL: %s\n", r.RequestURI)
-
- collector, err := newCollector(r.URL, s.APIKey, s.RateLimit)
- if err != nil {
- log.Print(err)
- return
- }
-
- registry := prometheus.NewRegistry()
-
- // These will be collected every time the /stock or /fund endpoint is reached.
- registry.MustRegister(
- &collector,
- queryCount,
- queryDuration,
- errorCount)
-
- // Delegate http serving to Promethues client library, which will call collector.Collect.
- h := promhttp.HandlerFor(registry, promhttp.HandlerOpts{})
- h.ServeHTTP(w, r)
-}
diff --git a/internal/server.go b/internal/server.go
new file mode 100644
index 0000000..70371c1
--- /dev/null
+++ b/internal/server.go
@@ -0,0 +1,109 @@
+// Package internal contains the implementation of this exporter.
+package internal
+
+import (
+ "fmt"
+ "net/http"
+ "strconv"
+ "strings"
+ "time"
+
+ "github.com/prometheus/client_golang/prometheus"
+ "github.com/prometheus/client_golang/prometheus/collectors"
+ "github.com/prometheus/client_golang/prometheus/promhttp"
+ "github.com/umatare5/twelvedata-exporter/config"
+ "github.com/umatare5/twelvedata-exporter/log"
+)
+
+// Server struct
+type Server struct {
+ ListenAddrAndPort string
+ ScrapePath string
+ Client *TwelvedataClient
+}
+
+// NewServer returns Twelvedata struct
+func NewServer(config *config.Config) (Server, error) {
+ return Server{
+ ListenAddrAndPort: config.WebListenAddress + ":" + strconv.Itoa(config.WebListenPort),
+ ScrapePath: config.WebScrapePath,
+ Client: NewTwelvedataClient(config.TwelvedataAPIKey),
+ }, nil
+}
+
+// Start starts the server
+func (s *Server) Start() {
+ reg := prometheus.NewRegistry()
+
+ // Add standard process and Go metrics.
+ reg.MustRegister(
+ collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}),
+ collectors.NewGoCollector(),
+ )
+
+ // Register handlers.
+ http.HandleFunc("/", s.help)
+ http.HandleFunc(s.ScrapePath, func(w http.ResponseWriter, r *http.Request) {
+ s.priceHandler(w, r)
+ })
+
+ log.Infof("Listening on port %s", s.ListenAddrAndPort)
+ srv := &http.Server{
+ Addr: s.ListenAddrAndPort,
+ Handler: nil,
+ ReadTimeout: time.Second * 10,
+ WriteTimeout: time.Second * 10,
+ }
+ log.Fatal(srv.ListenAndServe())
+}
+
+// priceHandler handles the "/price" endpoint. It creates a new collector with
+// the URL and a new prometheus registry to use that collector.
+func (s *Server) priceHandler(w http.ResponseWriter, r *http.Request) {
+ // The typical query is formatted as: ?symbols=AAA,BBB...&symbols=CCC,DDD...
+ // We fetch all symbols into a single slice.
+ syms := r.URL.Query()["symbols"]
+ if len(syms) == 0 {
+ log.Infof("missing symbols in the query: %s", r.RequestURI)
+ return
+ }
+ log.Infof("URL: %s\n", r.RequestURI)
+
+ var symbols []string
+ for _, sym := range syms {
+ symbols = append(symbols, strings.Split(sym, ",")...)
+ }
+
+ registry := prometheus.NewRegistry()
+
+ // These will be collected every time the /stock or /fund endpoint is reached.
+ registry.MustRegister(
+ newCollector(s.Client, symbols),
+ queryCount,
+ queryDuration,
+ errorCount,
+ )
+
+ // Delegate http serving to Promethues client library, which will call collector.Collect.
+ h := promhttp.HandlerFor(registry, promhttp.HandlerOpts{})
+ h.ServeHTTP(w, r)
+}
+
+// help returns a help message for those using the root URL.
+func (s *Server) help(w http.ResponseWriter, _ *http.Request) {
+ fmt.Fprintf(w, "Prometheus Twelvedta Exporter
")
+ fmt.Fprintf(w, "To fetch the price of quotes, your URL must be formatted as:
")
+ fmt.Fprintf(w, "http://%s/price?symbols=AAAA,BBBB,CCCC", s.ListenAddrAndPort)
+ fmt.Fprintf(w, "Examples:
")
+ fmt.Fprintf(w, "")
+
+ symbols := []string{
+ "GOOGL",
+ "AMZN,AAPL,MSFT",
+ }
+
+ for _, symbol := range symbols {
+ fmt.Fprintf(w, "- ", s.ListenAddrAndPort, symbol)
+ fmt.Fprintf(w, "http://%s/price?symbols=%s
", s.ListenAddrAndPort, symbol)
+ }
+}
diff --git a/internal/twelvedata.go b/internal/twelvedata.go
new file mode 100644
index 0000000..dc7aa0f
--- /dev/null
+++ b/internal/twelvedata.go
@@ -0,0 +1,139 @@
+// Package internal contains the implementation of this exporter.
+package internal
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "time"
+
+ "github.com/prometheus/client_golang/prometheus"
+ "github.com/umatare5/twelvedata-exporter/log"
+)
+
+var (
+ // These are metrics for the collector itself
+ queryDuration = prometheus.NewSummary(
+ prometheus.SummaryOpts{
+ Name: "twelvedata_query_duration_seconds",
+ Help: "Duration of queries to the upstream API",
+ },
+ )
+ queryCount = prometheus.NewCounter(
+ prometheus.CounterOpts{
+ Name: "twelvedata_queries_total",
+ Help: "Count of completed queries",
+ },
+ )
+ errorCount = prometheus.NewCounter(
+ prometheus.CounterOpts{
+ Name: "twelvedata_failed_queries_total",
+ Help: "Count of failed queries",
+ },
+ )
+)
+
+// TwelvedataGatherer is an interface for Twelvedata API
+type TwelvedataGatherer interface {
+ GetQuote(symbol string) (float64, error)
+}
+
+// TwelvedataClient is a client for Twelvedata API
+type TwelvedataClient struct {
+ baseURL string
+ apiKey string
+}
+
+// QuoteResponse is a response from twelvedata Quote endpoint
+type QuoteResponse struct {
+ Symbol string `json:"symbol"`
+ Name string `json:"name"`
+ Exchange string `json:"exchange"`
+ MicCode string `json:"mic_code"`
+ Currency string `json:"currency"`
+ Datetime string `json:"datetime"`
+ Timestamp int `json:"timestamp"`
+ Open string `json:"open"`
+ High string `json:"high"`
+ Low string `json:"low"`
+ Close string `json:"close"`
+ Volume string `json:"volume"`
+ PreviousClose string `json:"previous_close"`
+ Change string `json:"change"`
+ PercentChange string `json:"percent_change"`
+ AverageVolume string `json:"average_volume"`
+ IsMarketOpen bool `json:"is_market_open"`
+ FiftyTwoWeek fiftyTwoWeek `json:"fifty_two_week"`
+}
+
+type fiftyTwoWeek struct {
+ Low string `json:"low"`
+ High string `json:"high"`
+ LowChange string `json:"low_change"`
+ HighChange string `json:"high_change"`
+ LowChangePercent string `json:"low_change_percent"`
+ HighChangePercent string `json:"high_change_percent"`
+ Range string `json:"range"`
+}
+
+// NewTwelvedataClient returns Twelvedata Client.
+func NewTwelvedataClient(apiKey string) *TwelvedataClient {
+ return &TwelvedataClient{
+ baseURL: "https://api.twelvedata.com",
+ apiKey: apiKey,
+ }
+}
+
+// GetQuote sends GET request to Twelvedata API.
+func (t *TwelvedataClient) GetQuote(symbol string) (*QuoteResponse, error) {
+ client := &http.Client{
+ Timeout: time.Second * 10,
+ }
+
+ req, err := http.NewRequestWithContext(
+ context.Background(),
+ "GET",
+ fmt.Sprintf(t.baseURL+"/quote?symbol=%s&apikey=%s", symbol, t.apiKey),
+ nil,
+ )
+ if err != nil {
+ return nil, err
+ }
+
+ resp, err := client.Do(req)
+ if err != nil {
+ log.Errorf("Error sending request to server: %s", err)
+ return nil, err
+ }
+
+ defer func() {
+ err := resp.Body.Close()
+ if err != nil {
+ log.Errorf("Error closing response body: %s", err)
+ }
+ }()
+
+ body, err := io.ReadAll(resp.Body)
+ if err != nil {
+ log.Errorf("Error closing response body: %s", err)
+ return nil, err
+ }
+
+ var data QuoteResponse
+ err = json.Unmarshal(body, &data)
+ if err != nil {
+ log.Errorf("Error parsing JSON: %s", err)
+ return nil, err
+ }
+
+ if data.Name == "" {
+ log.Errorf("Name is not included in JSON: %s", err)
+ return nil, err
+ }
+
+ queryDuration.Observe(time.Since(time.Now()).Seconds())
+
+ return &data, nil
+}
diff --git a/log/logger.go b/log/logger.go
new file mode 100644
index 0000000..b891fab
--- /dev/null
+++ b/log/logger.go
@@ -0,0 +1,28 @@
+// Package log provides a simple logging interface.
+package log
+
+import (
+ "github.com/sirupsen/logrus"
+)
+
+var logger = logrus.New()
+
+// Info logs a message at level Info.
+func Info(args ...interface{}) {
+ logger.Info(args...)
+}
+
+// Infof logs a message at level Info.
+func Infof(format string, args ...interface{}) {
+ logger.Infof(format, args...)
+}
+
+// Errorf logs a message at level Error.
+func Errorf(format string, args ...interface{}) {
+ logger.Errorf(format, args...)
+}
+
+// Fatal logs a message at level Fatal.
+func Fatal(args ...interface{}) {
+ logger.Fatal(args...)
+}
diff --git a/prometheus.rules.sample.yml b/prometheus.rules.sample.yml
new file mode 100644
index 0000000..0f26e22
--- /dev/null
+++ b/prometheus.rules.sample.yml
@@ -0,0 +1,25 @@
+groups:
+ - name: technical_indicators
+ rules:
+ - record: twelvedata:technical:rsi:7
+ expr: 100 - (100 / (1 +
+ (
+ (
+ (
+ sum_over_time((delta(twelvedata_price[1h]) > 0)[9d:])
+ *
+ (count_over_time((twelvedata_change_percent > 0)[9d:]) - 1)
+ )
+ / count_over_time((twelvedata_change_percent > 0)[9d:])
+ )
+ /
+ abs(
+ (
+ sum_over_time((delta(twelvedata_price[1h]) < 0)[9d:])
+ *
+ (count_over_time((twelvedata_change_percent < 0)[9d:]) - 1)
+ )
+ / count_over_time((twelvedata_change_percent < 0)[9d:])
+ )
+ )
+ ))
diff --git a/prometheus.sample.yml b/prometheus.sample.yml
new file mode 100644
index 0000000..e244746
--- /dev/null
+++ b/prometheus.sample.yml
@@ -0,0 +1,42 @@
+# my global config
+global:
+ scrape_interval: 15s # By default, scrape targets every 15 seconds.
+ evaluation_interval: 15s # By default, scrape targets every 15 seconds.
+ # scrape_timeout is set to the global default (10s).
+
+# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
+rule_files:
+ # - "first.rules"
+ # - "second.rules"
+
+# A scrape configuration containing exactly one endpoint to scrape:
+# Here it's Prometheus itself.
+scrape_configs:
+ # The job name is added as a label `job=` to any timeseries scraped from this config.
+ - job_name: 'prometheus'
+
+ # Override the global default and scrape targets from this job every 5 seconds.
+ scrape_interval: 5s
+
+ # metrics_path defaults to '/metrics'
+ # scheme defaults to 'http'.
+
+ static_configs:
+ - targets: ['localhost:9090']
+
+ - job_name: "twelvedata"
+ metrics_path: /price
+ scrape_interval: 15m
+ scrape_timeout: 14m
+ params:
+ symbols: # Free tier allows up to 8 symbols per minute
+ - SPX # S&P500
+ - SOXL # Direxion Daily Technology Bull 3X Shares ETF
+ - TECL # Direxion Daily Semiconductor Bull 3X Shares
+ - GOOGL # Google
+ - AAPL # Apple
+ - AMZN # Amazon
+ - FB # Facebook
+ - VIX # CBOE Volatility Index
+ static_configs:
+ - targets: [localhost:9341]