A source can be thought of as a single member in a population that you are capturing the metric for. Think of it as a second identifying dimension we support in addition to 'name' for a metric.
For example the number of requests/second serviced by an application (metric) could be broken up amongst a group of server instances in a scale-out tier (source) by setting the hostname as the value of source in the measurement properties.
Hostname is probably the most common use-case but we make no assumption about "source" except that it distinguishes multiple homogenous "things" that all have the same metric, so instead of "hostname" you could use things like "customer_id" or "sensor_id" if you wanted.
Sources in the Metrics view
When you click on a metric in your metrics list, it will open the graph for the metric and below the graph it will list all its sources. As an example, we have a metric called api.measures.gets.reqs.total. Under the graph of the metric I can see all its sources:
I can drill down into specific sources or groups of sources by using the stream filter at the bottom of the page. For example if I type *prod* into the stream filter it shows me all production servers.
If no source is defined we default it to 'unassigned'.
Sources in the Instrument View
When you add a metric to an instrument a metric row is added under the graph which contains icons that let you change the source and the stream composition. Using the source dimension you can elect to show all sources of the metric, a subset (even a single source) or to change the source dynamically.
Selecting a Source
Clicking on the target icon in the row of the metric allows you to change the source.
By default, ALL sources is set as represented by the '*' wildcard.
SPECIFIC, as the name implies, allows you to enter the name of a specific source. You can also use wildcards to define a group of sources.
DYNAMIC allows you to select a source dynamically. The metric row will be marked with a [D] and a search box appears at the bottom of the screen.
Whenever you have selected to show more than one source for a metric, the stream composition let's you define how the data is aggregated over time and across the sources.
Click on the aggregation icon (looks like a tiny org chart) and a menu appears that allows you to define how you summarize across sources and over time.
The left box defines how you display the sources. BREAKOUT allows you to display all sources as separate lines on the graph. If you don't want separate lines you can show the average, sum, min, or max.
The right box defines how you summarize across time. This allows you, for example, to show one line that represents the the max of the averages across all sources.
Sources can be very powerful, particularly when used with a well designed naming convention. Read more about how to use sources in instruments or how to use sources to create instrument and dashboard templates.