# Python Pickle

Pickled data forms a list of multi-level tuples:

```
[(path, (timestamp, value)), ...]
```

You’ll need to pack your pickled data into a packet containing a simple header:

```
payload = pickle.dumps(listOfMetricTuples, protocol=2)
header = struct.pack("!L", len(payload))
message = header + payload
```

Once you’ve formed a list of sufficient size and pickled it, like `message` above, send the data over a TCP socket to `carbon.hostedgraphite.com:2004`.

Your API Key is prefixed to the metricname as per regular Python methods:

```
"YOUR-API-KEY.my.metric.name"
```

If you have any trouble or any questions, [contact us](mailto:help%40hostedgraphite.com).

### Carbon Relay

If you would prefer to use a carbon-relay daemon to send metric data to Hosted Graphite, just configure it to use `carbon.hostedgraphite.com:2004` as a `DESTINATION` in your `carbon.conf` and `relay-rules.conf` files.

`carbon.conf`:

```
[relay]
...
RELAY_METHOD = rules
DESTINATIONS = carbon.hostedgraphite.com:2004
```

`relay-rules.conf`:

```
[default]
default = true
destinations = carbon.hostedgraphite.com:2004
```

If you’re currently using the carbon-cache daemon and would like to utilize carbon-relay to send your metrics to us and also to your own carbon instance, you will have to send metrics to carbon-relay instead of carbon.

To do this, you have to configure carbon-relay to listen on the port that your current carbon-cache is listening. Then you will need to configure carbon-cache to listen on a new port.

You can then add your carbon-cache instance as a `DESTINATION` to have carbon-relay forward all metrics to Hosted Graphite AND your local carbon-cache

current carbon.conf:

```
[cache]
...
LINE_RECEIVER_PORT = 2003
PICKLE_RECEIVER_PORT = 2004
...

[relay]
...
RELAY_METHOD = rules
DESTINATIONS = carbon.hostedgraphite.com:2004
```

This should be changed to:

`new carbon.conf`:

```
[cache]
...
LINE_RECEIVER_PORT = 2013
PICKLE_RECEIVER_PORT = 2014
...

[relay]
...
RELAY_METHOD = rules
DESTINATIONS = carbon.hostedgraphite.com:2004, 127.0.0.1:2014
LINE_RECEIVER_PORT = 2003
PICKLE_RECEIVER_PORT = 2004
```

`relay-rules.conf`

```
[default]
default = true
destinations = carbon.hostedgraphite.com:2004, 127.0.0.1:2014
```

If you’re doing this and you’d like to avoid prefixing every metric with your API key, please [contact us to discuss alternatives](mailto:help%40hostedgraphite.com), including IP whitelisting, reach out for our live chat support.

### Carbon Relay Secured With Stunnel

If you want to encrypt the metric data from your Carbon Relay, you can use Stunnel. Carbon-Relay should be configured to send metrics to Stunnel over localhost

To install Stunnel:

```
sudo apt-get install stunnel
or
sudo yum install stunnel
```

**Configuring Stunnel**

Stunnel will need a configuration file. By default, Stunnel will look at `/etc/stunnel/stunnel.conf`. You may need to create this file yourself.

Put the following lines inside `/etc/stunnel/stunnel.conf`:

```
foreground = yes

[hg-tls]
client = yes
accept = 20041
connect = 72c4f55b.carbon.hostedgraphite.com:20040
verify = 2
CAfile = /etc/ssl/certs/ca-bundle.crt
#CApath = /etc/ssl/certs
```

* `foreground = yes`

  This shows the degbug logs. You may want to remove this line once Stunnel is configured and running correctly.
* `accept = <port>`

  Carbon relay must be configured to send metrics to `<port>`.
* connect = 72c4f55b.carbon.hostedgraphite.com:20040

  Hosted Graphite will accept Stunnel connections on port 20040
* `CAfile / CApath`

  You only need one of these. You will need to provide a path to your ssl certificates.

  * `CAfile` expects a certificate file. Some of the default locations of these files are:

    ```
    "/etc/ssl/certs/ca-certificates.crt"  // Debian/Ubuntu/Gentoo etc.
    "/etc/pki/tls/certs/ca-bundle.crt"    // Fedora/RHEL
    "/etc/ssl/ca-bundle.pem"              // OpenSUSE
    "/etc/pki/tls/cacert.pem"             // OpenELEC
    ```
  * CApath expects a directory containing certificates named `XXXXXXXX.0` where `XXXXXXXX` is the hash value of the DER encoded subject of the cert.

You can read more about Stunnel configuration options [here](https://www.stunnel.org/static/stunnel.html).

**Reconfiguring Carbon-Relay**

Carbon relay needs to send metrics to Stunnel now.

`carbon.conf`:

```
[relay]
...
DESTINATIONS = localhost:20041:stunnel
```

`relay-rules.conf`:

```
[default]
default = true
destinations = localhost:20041:stunnel
```

Now start Stunnel:

```
stunnel
```

**Note:** If your package manager downloaded stunnel4, you may have to start stunnel with:

```
stunnel4
```


---

# 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/language-guide/python-pickle.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.