Skip to content
TSL is a HTTP proxy which generate WarpScript or a PromQl script based on a TSL query.
Go ANTLR Makefile
Branch: master
Clone or download
PierreZ Merge pull request #76 from ovh/fix/var/numInString
fix(variable): fix numerical variable in Strings
Latest commit 6824d5f Nov 28, 2019

Time Series Language (TSL)

TSL is a HTTP proxy which generate WarpScript or a PromQl script based on a TSL query, then execute it on a Warp 10 or a Prometheus backend. To get more information about a TSL query, you can have a look at our initial spec and our query doc. Our ANTLR grammar definition is available in the antlr folder here.


To build and install Tsl you need:

  • A working go install, with the GOROOTand GOPATH variables correctly set
  • make in order to use the Makefile


  1. Install the tooling

    make init

  2. Grab the dependencies

    make dep

  3. Local build of TSL

    make dev

  4. Release build of TSL

    make release

Binary is now available in the directory build under the name tsl.


TSL needs a YAML configuration file with two entries:

  • tsl.default.endpoint
  • tsl.default.type

This is an example with a Warp 10 backend.

    endpoint: http//
    type: 'warp10'

TSL will look for a config.yml file on:

  • /etc/tsl/
  • $HOME/.tsl
  • the current path

You can also use the -c to set a configuration path for a TSL instance.

Without a configuaration file, TSL will use as default endpoint.

To use TSL on several backends you can specify the following optional parameters:




You can simply run the TSL binary, ./build/tsl.

By default, TSL listens on

$ ./build/tsl --config path/to/config.yml
INFO[0000] Start tsl server on

Query TSL

To send a TSL request, you can use the v0/query api endpoint to send TSL queries.

A TSL query can be:


This is a first TSL query, with the following methods used:

  • select to specify a metric name to retrieve (or pattern name).
  • where to set labels that the current Time-series must have.
  • from to select data between two dates.

You can send this request through an HTTP Post with the cURL Command line or any other HTTP tools like Insomnia or PostMan.

As example, we can write a new TSL file containing the previous script and send the cURL command below:

curl -v --data-binary @select.tsl 'https://user:password@'

This command provides as result a time-series JSON list.

TSL implements a lot of diffetent methods and you can find a more details in the spec folder.


If you need more complex options, use ./build/tsl --help:

$ ./build/tsl --help
A proxy that translates queries for a TSDB backend

  tsl [flags]
  tsl [command]

Available Commands:
  help        Help about any command
  version     Print the version number

  -c, --config string   config file (default is $HOME/.tsl.yaml)
  -h, --help            help for tsl
  -l, --listen string   listen address (default "")
  -v, --verbose         verbose output

Use "tsl [command] --help" for more information about a command.

Use TSL with WebAssembly

NOTE: A Go 1.11 (> go1.11.1) version at least is needed. Building tsl.wasm works with go 1.12.5.

You can run the TSL to WarpScript interpreter in a WebAssembly program. The tsl.wasm file export the method tslToWarpScript callable from JavaScript running in a browser or NodeJS.

To compile the tsl package for the web:

$ make wasm

As example, you can call the tslToWarpScript from a JavaScript program like that:

tslToWarpScript("select(\"sys.cpu.nice\").where(\"host=web01\").from(1346846400000,to=1346847000005)", "", false, (err, res) => {
	console.log(res) // Output the tsl query in a WarpScript syntax

To integrate the tsl.wasm file in your program, you should follow the Golang WebAssembly wiki.

Build TSL .so file to use TSL in other language

You can build TSL so library files, usable in other progamming language as describe in this github tutorial.

To compile TSL .so libray simply run

make so

In the spec folder, you can find a JAVA example of the .so TSL library.


See the LICENSE file.

Get in touch


Twitter: @AurrelH95

You can’t perform that action at this time.