{"__v":21,"_id":"564533f2b360ea0d009148b6","api":{"auth":"required","params":[],"results":{"codes":[]},"settings":"","url":""},"body":"This reference guide details the HTTP API for SignalFx. Using this API you can send [metric](doc:sending-data-points) and [event](doc:events-overview) data to SignalFx, manipulate [metadata](doc:metrics-metadata-overview), and [create detectors](doc:detector-template) or [clone dashboards](doc:cloning-dashboards). The [SignalFlow](doc:signalflow-overview) streaming analytics service is now also available in limited beta access via the HTTP API.\n\nYou can access the API directly by issuing HTTP requests to the appropriate endpoint or via our client libraries. All API endpoints, with the exception of the call to establish a session, are authenticated. When making an API call, set the **X-SF-Token** header to either the session token acquired from the call to /session, or your organization's API token which you can find on your profile page.\n\n# The SignalFx Metric Data Model\n\nMetric data are numerical measurements from your systems, often categorized in three tiers: infrastructure, application, and business metrics. Infrastructure metrics are about the machinery and services which applications rely on, such as disk usage, network utilization, or database statistics. Application metrics are often specific to software which are written by engineers at your organization, such as the amount of time an internal function call takes to return a value, or the number of times a method is called. Finally, business metrics describe high-level business metrics, such as the number of sales made or active users.\n\nSignalFx provides [out-of-the-box functionality](https://support.signalfx.com/hc/en-us/articles/203762079-Overview-of-SignalFx-integrations) to capture common infrastructure metrics, along with APIs and libraries to send custom application and business metrics. Our data model is designed to help gain insights into the behavior of not just individual metrics but your infrastructure, applications, and business as a whole.\n\nThis guide will focus on describing our data model, specifically metrics, time series, dimensions, custom properties, and tags, so that you can best leverage our platform.\n\n## Anatomy of a datapoint\nHere's an example of a metric datapoint request to SignalFx using HTTP which you can run in your command-line:\n```shell\n# Set the SignalFx API token which can be found in your Profile page in the app\nSF_TOKEN=\"YOUR API TOKEN\"\n\n# Send a datapoint via HTTP POST request using cURL\ncurl --request POST \\\n --header \"Content-Type: application/json\" \\\n --header \"X-SF-Token:$SF_TOKEN\" \\\n --data \\\n '{ \"gauge\": [{\n \"metric\": \"memory.free\",\n \"dimensions\": { \"host\": \"server1\" },\n \"value\": 42\n }]}' \\\n https://ingest.signalfx.com/v2/datapoint\n```\n\nThe above request will send a single datapoint to SignalFx: a gauge with the metric name of \"memory.free\" with a value of \"42\" and with the host dimension of \"server1\".\n\nEvery datapoint sent to SignalFx contains four pieces of information: metric value, metric name, metric type, and time series dimensions.\n\n### Metric value\nA number which represents some measurement from your system. Some examples of this are current cpu load, disk space, or page visits.\n\n### Metric name\nA name which identifies the values being sent in. For example: \"memory.free\", \"CPUUtilization\", \"transaction.cost\", \"page_visits\".\n\n### Metric type\nOne of our predefined types (gauge, counter, or cumulative_counter) which determine the rollup that SignalFx will use when combining multiple values for this metric.\n\nFor example, if you send multiple values for test.gauge within one second, we will combine them by averaging them to retain a one second resolution. So, sending \"40\" and \"50\" within one second will result in \"45\" being stored for that second. If the metric type were a \"counter\", then we would add the two values, resulting in \"90\" being stored instead.\n\n| Metric Type | Rollup | Example Rollup |\n|---------------------|---------|-----------------|\n| gauge | mean | (40, 50) -> 45 |\n| counter | sum | (40, 50) -> 90 |\n| cumulative_counter | max | (40, 50) -> 50 |\n\n### Time Series Dimensions\nTime series dimensions are custom key/value pairs in combination with the metric name that identify the metric time series. Dimensions and metric is effectively the compound key of the metric time series. For example, if two servers sent \"cpu.load\" without any additional dimensions, their values would be combined because SignalFx would treat all data received as part of a single time series. If each server added a dimension called \"host\" with the value as its host name (e.g., { \"host\" : \"server1\" } and { \"host\" : \"server2\" }) then SignalFx would create two time series, one for the \"cpu.load\" of \"server1\" and one for the \"cpu.load\" of \"server2\".\n\nDimensions are also useful in aggregating and filtering metrics. For example, sending an \"environment\" dimension with each datapoint would allow you to vary alerts based on the different environments that metrics are being sent from.\n\n## The Life of a Data Point\n\n### Time series\nWhen a data point is sent to SignalFx, we store it as part of a time series. A time series is the unique combination of a metric name and dimensions. It is automatically created whenever a datapoint is received with a metric+dimension combination that doesn't already exist in our system.\n\n### Custom Properties and Tags\nDimensions and metrics can be extended by adding custom properties or tags. This additional information can then be used when filtering or grouping time series.\n\nFor example, if you send { \"host\" : \"server1\" } as a dimension for all metrics coming from server1, any property you add to the host:server1 dimension will also be assigned to all time series involving that dimension. You can add custom properties via the Catalog in the app or via the API:\n```shell\n$ SFX_TOKEN=\"YOUR API TOKEN\"\n$ curl --request PUT \\\n --header \"X-SF-TOKEN: $SFX_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data \\\n '{ \"tags\": [],\n \"customProperties\": { \"region\" : \"japan\" }\n }' \\\n https://api.signalfx.com/v2/dimension/host/server1\n```\nNow that region:japan is a custom property of the host:server1 dimension, you can use it to search time series or group them for analytics. Tags behave similarly to custom properties, except that they're unary values. An example of a tag could be \"decommissioned\", which you could use to mark hosts which may still be sending metrics but are no longer in use so that you could exclude them from alerting.\n\nTags also have a special property in SignalFx where they too can be assigned custom properties. For example, if you had a tag named \"web-tier\" and you added a customer property of owner:applications to that tag (either via the Catalog or using the Tag API), that property will become associated with any dimensions or metrics which have been tagged with \"web-tier\".\n\n### Filtering and Grouping Time Series\nWhen charting or creating alerts for your data, you will be able to filter using a combination of metric names, dimensions, custom properties, and tags to find matching time series.\n\nThe simplest example is charting all data for a given metric by selecting the metric in the chart editor:\n\n\n\nYou can filter your dataset by using dimensions, custom properties, or tags. Here's an example of filtering down to one host:\n\n\n\nYou can also use shared dimensions or custom properties to group time series data together. Here's an example of getting the 95th percentile free memory by region.\n\n\n\nYou can also use dimensions, custom properties, and tags to search for metric time series. Here's an example using cURL:\n```shell\n# Set the SignalFx API token which can be found in your Profile page in the app\nSF_TOKEN=\"YOUR API TOKEN\"\n\n# The query parameter which we'll be searching with\nQUERY=\"region:japan AND NOT (host:server1 OR host:server2)\"\n\n# Execute the HTTP GET request to find metric time series which match the query\ncurl --header \"X-SF-TOKEN: $SF_TOKEN\" https://api.signalfx.com/v2/metrictimeseries?query=$QUERY\n```\n\nThe above query will find any time series which has the region:japan custom property or dimension, with the exception of time series which have \"server1\" and \"server2\" as the values for a \"host\" custom property or dimension. Note that when searching for time series, the query doesn't distinguish between dimensions or custom properties.\n\n## API Query Syntax\nOur [API search](https://developers.signalfx.com/docs/metrictimeseries) syntax is similar to [Lucene syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html). Queries are combinations of terms and operators, where terms are either single words (such as `server5`) or groups of words encapsulated in double quotes (such as `\"North Dakota\"`). You can limit a term query to a specific dimension or custom property key by specifying the field followed by a colon (`:`) then the term to search for (such as `region:japan`). Dimensions and custom properties are treated alike when searching, so queries such as `region:japan` would search both dimensions called \"region\" with the value \"japan\" along with custom properties which have the key \"region\" and value \"japan\".\n\n### AND / OR / NOT Operators\nBy default, terms are combined using the OR operator when making queries via the API. This means that given the query `region:japan host:server5`, the result set will contain objects which either have japan region and/or server5 host as a dimension or custom property.\n\nAND is used to require two terms to be present in each result. For example, searching `region:japan AND host:server5` would return results which have both the japan region and the server5 host as a dimension or custom property.\n\nNOT is used to exclude results which contain certain terms. For example, searching `region:japan AND NOT host:server5` would return results which contain the japan region so long as they don't include the server5 host as a dimension or custom property.\n\n### Grouping\nParenthesis can be used to group clauses. For example, the querying for `region:japan AND (host:server5 OR env:production)` would return results which contain the japan region and either the server5 host or the production env dimension or custom property.\n\n### Wildcard Searches\n`?`can be used as a single character wildcard and `*` can be used as a multiple character wildcard in single terms. For example, `host:webServer*` will return results which have the \"webServer\" prefix for values of the host dimension or custom property.\n\n### Range Queries\nNumeric range terms can be specified using brackets along with the TO operator. For example, `lastUpdated:[1420099200000 TO 1451635200000]` would return results which were last updated in the year 2015 (the numbers being milliseconds after Unix epoch).\n\nAlphabetic range terms can be specified using brackets along with the TO operator. For example, `customer:[Alice TO Charlie]` will return any results which contain a customer value between Alice and Charlie (inclusive).\n\nExclusive range queries can be made by using curly braces instead of square brackets. For example, `lastUpdated:{1420099200000 TO 1420099200002}` would only search for the lastUpdated value of 1420099200001.\n\n### Property Existence Checks\nYou can search for results containing a given property key (or not containing) by using the `_exists_` and `_missing_` pseudofields. For example, to find results which contain a `host_machine` property you can search for `_exists_:host_machine`.\n\n## Built-in Data Models\nOur open-source data collection agent (collectd) along with our AWS integration provides out-of-the-box functionality, each with it's own predefined data model which you can extend using custom properties and tags. If you're using the SignalFx agent or have an AWS integration, you will be able to filter and group by these custom properties in SignalFx.\n\n### collectd\nBy default [our collectd installer](https://support.signalfx.com/hc/en-us/articles/201094025-Use-collectd) will come with the [SignalFx metadata plugin](https://github.com/signalfx/signalfx-collectd-plugin) which provides adds useful custom properties to the host dimension associated with the host sending the metrics. If you have the plugin enabled for collectd you will be able to filter and group any time series reported by collectd with the host dimension using the custom properties below.\n\n| Property | Description |\n|-----------------------|------------------------------------------------------|\n| host_collectd_version | The version of [collectd](https://collectd.org/) running on the host |\n| host_cpu_cores | Number of cores within the CPU |\n| host_cpu_model | The model name of the CPU as reported by /proc/cpuinfo |\n| host_kernel_name | The System/OS name (e.g. 'Linux') |\n| host_kernel_release | The release number or name of the kernel |\n| host_kernel_version | Version of the host OS |\n| host_linux_version | Linux version running on host (on Linux machines) |\n| host_logical_cpus | Number of logical CPUs |\n| host_machine | The machine type (e.g. 'x86_64') |\n| host_mem_total | Total memory available on host |\n| host_metadata_version | Version of the SignalFx metadata plugin running on host |\n| host_physical_cpus | Number of physical CPUs |\n| host_processor | The name of the processor |\n| plugin | Name of the plugin reporting a time series |\n| plugin_instance | Name of the plugin instance reporting a time series|\n\nIn addition to the properties above, each collectd plugin may provide additional dimension with the metrics it sends. For example, the elasticsearch plugin adds the elasticsearch index name as the `index` dimension for the metrics it sends.\n\nYou can use these any of these properties to search for hosts or time series in the application or via the API. For example, to find all hosts running collectd 5.4.1, you can execute the following against our API:\n```shell\n# Set the SignalFx API token which can be found in your Profile page in the app\nSF_TOKEN=\"YOUR API TOKEN\"\n\n# The query parameter which we'll be searching with\nQUERY=\"sf_key:host AND host_collectd_version:5.4.1\"\n\n# Execute the HTTP GET request to find dimensions which match the query\ncurl --header \"X-SF-TOKEN: $SF_TOKEN\" https://api.signalfx.com/v2/dimension?query=$QUERY\n```\n\n#### collectd plugins\n\n\n### Amazon Web Services (AWS)\nWhen [AWS integration](https://support.signalfx.com/hc/en-us/articles/204422055-Integrate-with-Amazon-Web-Services) is enabled, SignalFx will add EC2 metadata to any AWSUniqueId dimension which matches the unique id of an EC2 instance found within the integrated AWS account.\n\nAWS metadata integration provides additional custom properties which you can use to filter and group time series by. If you are using our collectd agent to report metrics from your EC2 instances, we will automatically add the AWSUniqueId dimension to data sent via the agent so that any time series originating from the instance will benefit from AWS metadata integration.\n\n| Custom Property | Description |\n|-----------------------|----------------------------------------------------------|\n| aws_architecture | Instance architecture (i386 or x86_64) |\n| aws_hypervisor | Hypervisor type of the instance (ovm or xen) |\n| aws_image_id | ID of the image used to launch the instance |\n| aws_instance_id | ID of the instance |\n| aws_kernel_id | Kernel ID |\n| aws_public_ip_address | The address of the Elastic IP address bound to the network interface |\n| aws_root_device_type | Type of root device that the instance uses |\n| aws_launch_time | The time when the instance was launched |\n| aws_region | The region which the instance is running in |\n| aws_account_alias | AWS account alias which the instance is running under |\n| aws_account_id | AWS account id which the instance is running under |\n| aws_availability_zone | The availability zone of the instance |\n| aws_instance_type | Type of the instance |\n| aws_private_dns_name | Private DNS name of the instance |\n| aws_public_dns_name | Public DNS name of the instance |\n| aws_reservation_id | ID of the instance's reservation |\n| aws_state | An object defining the state code and name of the instance |\n| aws_state_reason | The state reason for the instance (if provided) |\n| aws_tag_[Name of tag] | Custom tags applied to the instance (e.g., aws_tag_Name) |\n\nFor example, to find all hosts in the us-east-1a availability zone, you\ncan execute the following against our API:\n```shell\n# Set the SignalFx API token which can be found in your Profile page in the app\nSF_TOKEN=\"YOUR API TOKEN\"\n\n# The query parameter which we'll be searching with\nQUERY=\"sf_key:host AND aws_availability_zone:us-east-1a\"\n\n# Execute the HTTP GET request to find dimensions which match the query\ncurl --header \"X-SF-TOKEN: $SF_TOKEN\" https://api.signalfx.com/v2/dimension?query=$QUERY\n```","category":"564533dc6b0ca50d00f6bdcf","createdAt":"2015-11-13T00:50:58.963Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"parentDoc":null,"project":"5644e8bed608df0d00d269d9","slug":"signalfx-api-overview","sync_unique":"","title":"SignalFx API Overview","type":"basic","updates":[],"user":"5644e82bb360ea0d00914817","version":"5644e8f22229d7170010923b","childrenPages":[]}