# Sitespeed

[Sitespeed.io](https://www.sitespeed.io/) is an open-source tool that runs on Docker and can be used for analyzing website performance helping you identify bottlenecks, and optimize your web pages. Sitespeed has a Graphite output and can be easily configured to send metrics to your Hosted Graphite account.

**Send Sitespeed Metrics to Hosted Graphite**

You can run the following Docker command against any website URL that you wish to test: 

`docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:29.2.0 <URL-of-website-to-test> --graphite.host carbon.hostedgraphite.com --graphite.port 2003 --graphite.namespace <YOUR-API-KEY>.sitespeed_io.default.hg`

Running this command will send website performance metrics to your Hosted Graphite account and you can easily visualize them by importing various auto-dashboards from the Sitespeed GitHub [repository](https://github.com/sitespeedio/grafana-bootstrap-docker/tree/83dc8cbf572126e3f40b6b7a5053dae1a5701d20/dashboards/graphite). We also have a Sitespeed Performance dashboard that has been optimized for Hosted Graphite, located in our [Dashboard Library](https://docs.hostedgraphite.com/dashboard-and-graphs/dashboard-library). Event data will also be stored locally after each run, so it is recommended to run the command from within a designated directory.

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2Fu0VJNIAx6k2QnwAENYqg%2Fsitespeed-performance-dashboard.png?alt=media&#x26;token=6ec03d6b-179f-4a94-b7df-db1f9eefe98a" alt=""><figcaption><p>Sitespeed Performance Dashboard</p></figcaption></figure>

**Sending Annotations**

To send Sitespeed annotations to Hosted Graphite you must add some required [configuration options](https://www.sitespeed.io/documentation/sitespeed.io/configuration/#the-options) to your docker run command, such as:&#x20;

```
--graphite.webHost www.hostedgraphite.com
--graphite.proxyPath /api/v1/graphite/events/
--graphite.httpPort 443
--graphite.auth <YOUR-API-KEY>:
--graphite.resultBaseURL https://result.sitespeed.io
--graphite.sendAnnotation true
```

Additionally, you can create a file at the root of your sitespeed directory named **config.json** to store all of the required `--graphite` options and run a cleaner command. Here is a template for a **config.json** file with all of the required Graphite options to include annotations, and a parameter that better aligns the annotations with our default aggregation resolution of 30s:

```json
{
  "graphite": {
    "host": "carbon.hostedgraphite.com",
    "port": 2003,
    "namespace": "<YOUR-API-KEY>.sitespeed_io.default.hg",
    "webHost": "www.hostedgraphite.com",
    "proxyPath": "/api/v1/graphite/events/",
    "httpPort": 443,
    "auth": "<YOUR-API-KEY>:",
    "sendAnnotation": true,
    "annotationRetentionMinutes": ".5" 
    },
   "resultBaseURL": "https://result.sitespeed.io"
}
```

Save the file then run the Docker command using the **--config** option:

`docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:29.2.0 <URL-of-website-to-test> --config config.json`

Additionally, you could run Sitespeed tests against multiple URL's by listing them in a separate file and including it in the docker run command:

Create a new file: `urls.txt`

```
  https://www.<url-1>.com/
  https://www.<url-2>.com/
  https://www.<url-3>.com/
```

Save the file and run the Docker command with the new file name in place of the URL:

`docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:29.2.0 urls.txt --config config.json`

To only run 1 iteration of tests instead the default iteration of 3, that can also be specified in the docker run command by using the `-n` flag:

`docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:29.2.0 urls.txt --config config.json -n 1`

**Visualizing Annotations**

Default annotations are sent by Sitespeed with tags that will match the following dashboard variables, as defined in the Sitespeed Performance dashboard:

**$base $path $group $page $browser $connectivity $testname**

These tags can be located in the **Go to result** annotation rule in the Page Metrics Auto Dash:

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FfNQmfs7IIFkipP27Xpqt%2Fsitespeed-annotations-v9.png?alt=media&#x26;token=c64cff17-89a1-425c-93bc-b8d6ff4752bf" alt=""><figcaption><p>Sitespeed Annotations</p></figcaption></figure>

These default tags allow you to toggle between domains and visualize event annotations that correspond to each URL that Sitespeed was run against. Generally you only need to query the **$base $group $page $browser $connectivity** variables to see annotations on the Sitespeed Performance dashboard (annotations might not appear as expected with every default variable in place).