Great question! Unfortunately I don't know of any document as such, but I can give you the benefit of my own experiences.....
Rate Shaping: People often make the mistake of trying to make this too complicated. They try to identify which clients they should rate shape by checking user agents, tracking requests, behaviour etc, etc. It's all possible ofcourse, but you can end up in a never ending arms race. The simpler solution is to treat everyone like an end customer, determine what a normal rate would be and then apply that rate to every client equally. You should also determine if you want Stingray to block on requests which exceed the rate. If you use rate.use() once the rate is exceeded the request is held in a queue, if you would rather handle excess requests in TrafficScript your self then use rate.use.noqueue() instead. If you do use Stingrays queue, then check out rate.getBacklog() to stop the queue growing indefinitely.
Service Protection: This has many useful features including connection limiting. If you're worried about DOS and robots then it's worth looking at connection limiting to restrict how many concurrent connections each client can use and how quickly they can open new ones. Be careful if you're thinking about the HTTP specific options though, it's just possibly your application is not as RFC compliant as you think it is. The nice thing about service protection is the test mode. In test mode Stingray will just log requests which breach the policy without actually dropping them, which gives you the opportunity to try it out before you commit to anything.
Bandwidth classes: These are less flexible than rate classes. A rate class is applied by TrafficScript and can be given context (such as remote IP, or SessionID, etc), such that it can be applied to individuals, groups, or globally. Bandwidth management is applied globally, that is any connections put into the class share the bandwidth with each other. Also with incoming data, Stingray can at most zero a TCP window if it's not processing any more data at the time. A malicious client could still fill your pipe. Stingray can only marshall how the data is then forwarded onto the server pool.
Remeber the beauty of TrafficScript is that you can write rules and apply them on the fly. If you fo ever get attacked, then Stingray has your back! ;-)
Oh did I mention the Application Firewall module???
Hope that helps!
Mark
