# 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: 

{% code overflow="wrap" %}

```
docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:39.5.0 <FULL-URL-OF-SITE-TO-TEST> -n 1 --graphite.host carbon.hostedgraphite.com --graphite.port 2003 --graphite.namespace <YOUR-API-KEY>.sitespeed_io.default.hg
```

{% endcode %}

Running this command will send site 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](/dashboard-and-graphs/dashboard-library.md). 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="/files/CQdx459ayJK1LJvcMGNU" 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:39.5.0 <URL-of-website-to-test> --config config.json`

You can also 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:39.5.0 urls.txt --config config.json`

#### 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="/files/AkQvX4TpqmN8tz0IMIid" 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).

#### Metric Reduction Options

Sitespeed.io generates a large number of metrics by default, which can increase metric usage in Hosted Graphite. If you need to reduce the number of metrics collected, you can disable sets like summary statistics using `--browsertime.statistics false`, which reduces metrics the forwarded, or use the `--metrics.filter` option to include only specific groups (e.g: `--metrics.filter "*-" --metrics.filter "browsertime.pageSummary.statistics.googleWebVitals.*"` to keep only Core Web Vitals).

Keep in mind that filtering metrics may cause some panels in the default Grafana dashboards to stop displaying data, so it’s best used when you only need a subset of performance metrics.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostedgraphite.com/add-ons-and-integrations-guide/sitespeed.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.